yaze/docs/internal/wasm/api_reference.md

Yaze WASM JavaScript API Reference

Note

: For a general debugging walkthrough, see the WASM Debugging Guide.

Overview

The yaze WASM build exposes a comprehensive set of JavaScript APIs for programmatic control and data access. These APIs are organized into six main namespaces:

• window.yaze.control - Editor control and manipulation
• window.yaze.editor - Query current editor state
• window.yaze.data - Read-only access to ROM data
• window.yaze.gui - GUI automation and interaction
• window.yaze.agent - AI agent integration (chat, proposals, configuration)
• window.yazeDebug - Debug utilities and diagnostics
• window.aiTools - High-level AI assistant tools (Gemini Antigravity)

API Version

• Version: 2.5.0
• Last Updated: 2025-11-27
• Capabilities: ['palette', 'arena', 'graphics', 'timeline', 'pixel-inspector', 'rom', 'overworld', 'emulator', 'editor', 'control', 'data', 'gui', 'agent', 'loading-progress', 'ai-tools', 'async-editor-switch', 'card-groups', 'tree-sidebar', 'properties-panel']

Build Requirements

The WASM module must be built with these Emscripten flags for full API access:

-s MODULARIZE=1
-s EXPORT_NAME='createYazeModule'
-s EXPORTED_RUNTIME_METHODS=['FS','ccall','cwrap','lengthBytesUTF8','stringToUTF8','UTF8ToString','getValue','setValue']
-s INITIAL_MEMORY=268435456   # 256MB initial heap
-s ALLOW_MEMORY_GROWTH=1      # Dynamic heap growth
-s MAXIMUM_MEMORY=1073741824  # 1GB max
-s STACK_SIZE=8388608         # 8MB stack

The dev server must set COOP/COEP headers for SharedArrayBuffer support. Use ./scripts/serve-wasm.sh which handles this automatically.

Memory Configuration

The WASM build uses optimized memory settings to reduce heap resize operations during ROM loading:

• Initial Memory: 256MB - Reduces heap resizing during overworld map loading (~200MB required)
• Maximum Memory: 1GB - Prevents runaway allocations
• Stack Size: 8MB - Handles recursive operations during asset decompression

Quick Start

Check if API is Ready

// All control APIs share the same ready state
if (window.yaze.control.isReady()) {
  // APIs are available
}

Basic Example

// Switch to Dungeon editor
window.yaze.control.switchEditor('Dungeon');

// Get current editor state
const snapshot = window.yaze.editor.getSnapshot();
console.log('Active editor:', snapshot.editor_type);

// Get room tile data
const roomData = window.yaze.data.getRoomTiles(0);
console.log('Room dimensions:', roomData.width, 'x', roomData.height);

// Get available layouts
const layouts = window.yaze.control.getAvailableLayouts();
console.log('Available layouts:', layouts);

---

window.yaze.control - Editor Control API

Provides programmatic control over the editor UI, ROM operations, and session management.

Utility

isReady()

const ready = window.yaze.control.isReady()
// Returns: boolean

Checks if the control API is initialized and ready for use.

Editor Control

switchEditor(editorName)

window.yaze.control.switchEditor('Dungeon')
window.yaze.control.switchEditor('Overworld')
window.yaze.control.switchEditor('Graphics')

Parameters:

• editorName (string): Name of editor to switch to
  • Valid values: "Overworld", "Dungeon", "Graphics", "Palette", "Sprite", "Music", "Message", "Screen", "Assembly", "Hex", "Agent", "Settings"

Returns:

{
  "success": true,
  "editor": "Dungeon"
}

getCurrentEditor()

const editor = window.yaze.control.getCurrentEditor()

Returns:

{
  "name": "Dungeon",
  "type": 1,
  "active": true
}

getAvailableEditors()

const editors = window.yaze.control.getAvailableEditors()

Returns:

[
  {"name": "Overworld", "type": 0},
  {"name": "Dungeon", "type": 1},
  {"name": "Graphics", "type": 2}
]

Card Control

Cards are dockable panels within each editor.

openCard(cardId)

window.yaze.control.openCard('dungeon.room_selector')

Parameters:

• cardId (string): Card identifier

Returns:

{
  "success": true,
  "card_id": "dungeon.room_selector",
  "visible": true
}

closeCard(cardId)

window.yaze.control.closeCard('dungeon.room_selector')

Returns:

{
  "success": true,
  "card_id": "dungeon.room_selector",
  "visible": false
}

toggleCard(cardId)

window.yaze.control.toggleCard('dungeon.room_selector')

getVisibleCards()

const cards = window.yaze.control.getVisibleCards()

getAvailableCards()

const cards = window.yaze.control.getAvailableCards()

getCardsInCategory(category)

const cards = window.yaze.control.getCardsInCategory('Dungeon')

Layout Control

setCardLayout(layoutName)

window.yaze.control.setCardLayout('dungeon_default')

Parameters:

• layoutName (string): Name of layout preset

Returns:

{
  "success": true,
  "layout": "dungeon_default"
}

getAvailableLayouts()

const layouts = window.yaze.control.getAvailableLayouts()

Returns:

[
  "overworld_default",
  "dungeon_default",
  "graphics_default",
  "debug_default",
  "minimal",
  "all_cards"
]

saveCurrentLayout(layoutName)

window.yaze.control.saveCurrentLayout('my_custom_layout')

Menu/UI Actions

triggerMenuAction(actionPath)

window.yaze.control.triggerMenuAction('File.Save')

Parameters:

• actionPath (string): Menu path (format: "Menu.Action")

getAvailableMenuActions()

const actions = window.yaze.control.getAvailableMenuActions()

Session Control

getSessionInfo()

const info = window.yaze.control.getSessionInfo()

Returns:

{
  "session_index": 0,
  "session_count": 1,
  "rom_loaded": true,
  "rom_filename": "zelda3.sfc",
  "rom_title": "THE LEGEND OF ZELDA",
  "current_editor": "Dungeon"
}

createSession()

const result = window.yaze.control.createSession()

switchSession(sessionIndex)

window.yaze.control.switchSession(0)

ROM Control

getRomStatus()

const status = window.yaze.control.getRomStatus()

Returns:

{
  "loaded": true,
  "filename": "zelda3.sfc",
  "title": "THE LEGEND OF ZELDA",
  "size": 1048576,
  "dirty": false
}

readRomBytes(address, count)

const bytes = window.yaze.control.readRomBytes(0x10000, 32)

Parameters:

• address (number): ROM address to read from
• count (number, optional): Number of bytes (default: 16, max: 256)

writeRomBytes(address, bytes)

window.yaze.control.writeRomBytes(0x10000, [0x00, 0x01, 0x02, 0x03])

Parameters:

• address (number): ROM address to write to
• bytes (array): Array of byte values (0-255)

saveRom()

const result = window.yaze.control.saveRom()

---

window.yaze.editor - Editor State API

Query current editor state.

getSnapshot()

const snapshot = window.yaze.editor.getSnapshot()

Get comprehensive snapshot of current editor state.

getCurrentRoom()

const room = window.yaze.editor.getCurrentRoom()

Get current dungeon room (only in Dungeon editor).

getCurrentMap()

const map = window.yaze.editor.getCurrentMap()

Get current overworld map (only in Overworld editor).

getSelection()

const selection = window.yaze.editor.getSelection()

Get current selection in active editor.

---

window.yaze.data - Read-only Data API

Access ROM data without modifying it.

Dungeon Data

getRoomTiles(roomId)

const tiles = window.yaze.data.getRoomTiles(0)

Get tile data for a dungeon room.

Parameters:

• roomId (number): Room ID (0-295)

getRoomObjects(roomId)

const objects = window.yaze.data.getRoomObjects(0)

Get tile objects in a dungeon room.

getRoomProperties(roomId)

const props = window.yaze.data.getRoomProperties(0)

Get properties for a dungeon room.

Overworld Data

getMapTiles(mapId)

const tiles = window.yaze.data.getMapTiles(0)

Get tile data for an overworld map.

Parameters:

• mapId (number): Map ID (0-159)

getMapEntities(mapId)

const entities = window.yaze.data.getMapEntities(0)

Get entities (entrances, exits, items, sprites) on a map.

getMapProperties(mapId)

const props = window.yaze.data.getMapProperties(0)

Get properties for an overworld map.

Palette Data

getPalette(groupName, paletteId)

const palette = window.yaze.data.getPalette('ow_main', 0)

Get palette colors.

Parameters:

• groupName (string): Palette group name
• paletteId (number): Palette ID within group

getPaletteGroups()

const groups = window.yaze.data.getPaletteGroups()

Get list of available palette groups.

---

window.yaze.gui - GUI Automation API

For LLM agents to interact with the ImGui UI.

UI Discovery

discover()

const elements = window.yaze.gui.discover()

Get complete UI element tree for discovery and automation.

getElementBounds(elementId)

const bounds = window.yaze.gui.getElementBounds('dungeon_room_selector')

Get precise bounds for a specific UI element.

waitForElement(elementId, timeoutMs)

const bounds = await window.yaze.gui.waitForElement('dungeon_room_selector', 5000)

Wait for an element to appear.

Interaction

click(target)

window.yaze.gui.click('dungeon_room_selector')
// OR
window.yaze.gui.click({x: 100, y: 200})

Simulate a click at coordinates or on an element by ID.

doubleClick(target)

window.yaze.gui.doubleClick('dungeon_room_selector')

Simulate a double-click.

drag(from, to, steps)

window.yaze.gui.drag({x: 0, y: 0}, {x: 100, y: 100}, 10)

Simulate a drag operation.

pressKey(key, modifiers)

window.yaze.gui.pressKey('Enter', {ctrl: true})

Send a keyboard event to the canvas.

type(text, delayMs)

await window.yaze.gui.type('Hello World', 50)

Type a string of text.

scroll(deltaX, deltaY)

window.yaze.gui.scroll(0, 100)

Scroll the canvas.

Canvas & State

takeScreenshot(format, quality)

const dataUrl = window.yaze.gui.takeScreenshot('png', 0.92)

Take a screenshot of the canvas.

getCanvasInfo()

const info = window.yaze.gui.getCanvasInfo()

Get canvas dimensions and position.

updateCanvasState()

const state = window.yaze.gui.updateCanvasState()

Update canvas data-* attributes with current editor state.

startAutoUpdate(intervalMs)

window.yaze.gui.startAutoUpdate(500)

Start automatic canvas state updates.

stopAutoUpdate()

window.yaze.gui.stopAutoUpdate()

Stop automatic canvas state updates.

Card Management

getAvailableCards()

const cards = window.yaze.gui.getAvailableCards()

Get all available cards with their metadata.

showCard(cardId)

window.yaze.gui.showCard('dungeon.room_selector')

Show a specific card.

hideCard(cardId)

window.yaze.gui.hideCard('dungeon.room_selector')

Hide a specific card.

Selection

getSelection()

const selection = window.yaze.gui.getSelection()

Get the current selection in the active editor.

setSelection(ids)

window.yaze.gui.setSelection(['obj_1', 'obj_2'])

Set selection programmatically.

---

window.yaze.agent - AI Agent Integration API

Provides programmatic control over the AI agent system from JavaScript. Enables browser-based AI agents to interact with the built-in chat, manage proposals, and configure AI providers.

Utility

isReady()

const ready = window.yaze.agent.isReady()
// Returns: boolean

Checks if the agent system is initialized and ready for use. Requires ROM to be loaded.

Chat Operations

sendMessage(message)

const result = window.yaze.agent.sendMessage("Help me analyze dungeon room 0")

Send a message to the AI agent chat.

Parameters:

• message (string): User message to send

Returns:

{
  "success": true,
  "status": "queued",
  "message": "Help me analyze dungeon room 0"
}

getChatHistory()

const history = window.yaze.agent.getChatHistory()

Get the chat message history.

Returns:

[
  {"role": "user", "content": "Hello"},
  {"role": "assistant", "content": "Hi! How can I help?"}
]

Configuration

getConfig()

const config = window.yaze.agent.getConfig()

Get current agent configuration.

Returns:

{
  "provider": "mock",
  "model": "",
  "ollama_host": "http://localhost:11434",
  "verbose": false,
  "show_reasoning": true,
  "max_tool_iterations": 4
}

setConfig(config)

window.yaze.agent.setConfig({
  provider: "ollama",
  model: "llama3",
  ollama_host: "http://localhost:11434",
  verbose: true
})

Update agent configuration.

Parameters:

• config (object): Configuration object with optional fields:
  • provider: AI provider ID ("mock", "ollama", "gemini")
  • model: Model name/ID
  • ollama_host: Ollama server URL
  • verbose: Enable verbose logging
  • show_reasoning: Show AI reasoning in responses
  • max_tool_iterations: Max tool call iterations

Returns:

{
  "success": true
}

getProviders()

const providers = window.yaze.agent.getProviders()

Get list of available AI providers.

Returns:

[
  {
    "id": "mock",
    "name": "Mock Provider",
    "description": "Testing provider that echoes messages"
  },
  {
    "id": "ollama",
    "name": "Ollama",
    "description": "Local Ollama server",
    "requires_host": true
  },
  {
    "id": "gemini",
    "name": "Google Gemini",
    "description": "Google's Gemini API",
    "requires_api_key": true
  }
]

Proposal Management

getProposals()

const proposals = window.yaze.agent.getProposals()

Get list of pending/recent code proposals.

Returns:

[
  {
    "id": "proposal-123",
    "status": "pending",
    "summary": "Modify room palette"
  }
]

acceptProposal(proposalId)

window.yaze.agent.acceptProposal("proposal-123")

Accept a proposal and apply its changes.

rejectProposal(proposalId)

window.yaze.agent.rejectProposal("proposal-123")

Reject a proposal.

---

window.yazeDebug - Debug Utilities

Low-level debugging tools for the WASM environment.

dumpAll()

window.yazeDebug.dumpAll()

Dump full application state to console.

graphics.getDiagnostics()

window.yazeDebug.graphics.getDiagnostics()

Get graphics subsystem diagnostics.

memory.getUsage()

window.yazeDebug.memory.getUsage()

Get current memory usage statistics.

---

window.aiTools - High-Level Assistant Tools

Helper functions for the Gemini Antigravity agent.

getAppState()

window.aiTools.getAppState()

Get high-level application state summary.

getEditorState()

window.aiTools.getEditorState()

Get detailed state of the active editor.

getVisibleCards()

window.aiTools.getVisibleCards()

List currently visible UI cards.

getAvailableCards()

window.aiTools.getAvailableCards()

List all available UI cards.

showCard(cardId)

window.aiTools.showCard(cardId)

Show a card (wrapper for window.yaze.control.openCard).

hideCard(cardId)

window.aiTools.hideCard(cardId)

Hide a card.

navigateTo(target)

window.aiTools.navigateTo(target)

Navigate to a specific editor or view.

getRoomData(roomId)

window.aiTools.getRoomData(roomId)

Get dungeon room data.

getMapData(mapId)

window.aiTools.getMapData(mapId)

Get overworld map data.

dumpAPIReference()

window.aiTools.dumpAPIReference()

Dump this API reference to the console.