hearth

How Hearth works

Hearth is a 2D game engine you can drive by hand or hand to a coding agent. Both go through the same commands, so anything you can do in the editor, your agent can do from a terminal.

Point your agent at your project

Register the MCP server, or skip MCP and use the CLI. Both land on the same commands and the same project folder.

Have it call get_agent_instructions first for the house rules and active modes. MCP guide CLI guide

Everything goes through one command list

71 engine commands, each validated against a schema before it runs. If it is not a registered command, nothing can do it, your agent included.

  • get_project_info
  • inspect_scene
  • inspect_entity
  • list_components
  • inspect_api
  • inspect_path
  • validate_project
  • create_entity
  • add_component
  • set_component_property
  • set_properties
  • update_settings
  • create_script
  • attach_script
  • edit_script
  • check_script
  • format_script
  • search_scripts
  • replace_in_scripts
  • create_sprite_asset
  • create_sound
  • import_assets
  • paint_tiles
  • set_tile_autotile
  • create_prefab
  • instantiate_prefab
  • sync_prefab_instances
  • snapshot_project
  • get_diff
  • revert_project
  • undo
  • redo
  • list_history
  • list_journal
  • create_playtest
  • run_playtest
  • run_scene
  • export_web
  • export_desktop
  • get_agent_instructions
  • + 30 more

Where those 71 live:

How the command layer is built

Your agent gets a real answer back

Every call returns the same JSON shape, so your agent reads fields instead of scraping your terminal.

Error codes are fixed strings, never sentences:

  • NOT_FOUND
  • INVALID_PARAMS
  • SCHEMA_ERROR
  • PERMISSION_DENIED
  • CONFLICT
  • UNKNOWN_COMMAND
  • INTERNAL_ERROR

Nothing it does is hidden or permanent

The journal, the diff, and the playtests work the same whether a command came from you or from an agent.

Command journal

Every mutating command from every session, kept separate from undo.

Structural diff

What actually changed, with one-click revert in the editor's review panel.

Headless playtests

Scripted input, then assertions, at a fixed timestep. hearth test exits 1 on failure.

You decide what it is allowed to touch

Sessions carry a grant, commands declare what they need. The engine enforces it, not the prompt.

A denied call returns PERMISSION_DENIED naming the mode it was missing.

From an empty folder to a game you can ship

About ten minutes, and the steps are the same whether you type them or your agent does.

  1. Create

    hearth init

  2. Behave

    hearth create script

  3. Check

    hearth test

  4. Ship

    hearth export web

The export is a static build ready for itch.io, booting straight into your own first scene with no engine branding. Quickstart Export guide Download Hearth