dungeoncraft/AGENTS.md

DungeonCraft Agent Instructions

Commit and push workflow

Always commit and push after every completed, meaningful change in this repository. This keeps changes easy to review and easy to revert.

• Commit often: commit and push right after every completed logical change, not in large batches at the end of a session.
• Do not leave finished code changes uncommitted.
• One commit should represent one coherent change or one coherent follow-up step.
• Do not deploy, rebuild the public version, bump the version, or push deployment changes unless the user explicitly asks for deployment.
• Before committing, check git status and only stage files that belong to the intended change.
• Do not commit secrets, credentials, tokens, private keys, local server credentials, or generated build artifacts.

Commit messages

Write short English commit messages. Prefer a concise imperative style, matching the existing repository history.

Examples:

Add mission script actions
Debug FPS display with rendering backend info
Co-op campaign matches and command markers

Avoid vague messages such as fix, update, or changes.

Checks before committing

For normal Rust code changes, run at least:

cargo check --all-targets
cargo test

For changes that must remain runnable in the browser, also run:

cargo check --release --target wasm32-unknown-unknown

If the full test suite takes too long and only a focused area changed, it is acceptable to run the relevant targeted tests first, for example:

cargo test --bins script::
cargo test campaign::
cargo test game::

But before committing a completed change, the full local checks should pass unless there is a clear reason not to run them.

Repository conventions

• The repository uses Rust with Rhai for mission scripting.
• The campaign editor lives in src/editor/, the campaign file format in src/campaign_doc.rs, block scripts in src/blocks.rs and src/mscript.rs.
• Main runtime integration lives in src/main.rs.
• Campaign mission conversion and custom mission gameplay live in src/campaign.rs.
• UI/editor buttons and menus live in src/menu.rs and src/ui.rs.
• Language files live in lang/en.lang and lang/de.lang; keep German and English labels in sync.
• Campaign and mission scripting documentation lives in docs/CAMPAIGN_EDITOR.md and docs/MISSION_SCRIPTING.md.

Language conventions

• User-facing UI labels require both English and German entries in the language files.
• Keep campaign.* labels synchronized between lang/en.lang and lang/de.lang.
• Keep msg.script* labels synchronized between lang/en.lang and lang/de.lang.

Campaign scripting conventions

• Mission scripts are blocks (src/blocks.rs), edited in the in-game block editor (src/editor/blocks_ui.rs); players never see code.
• The blocks are run directly by the interpreter in src/mscript.rs inside the fixed simulation step (deterministic, co-op safe); there is no scripting language underneath (Rhai was removed when "wait" came).
• Script runs are threads (resumable after "wait", saved with the game); loops have a step budget per check so nothing can hang.
• Per mission: special scripts (start, victory check, defeat check, clock) and triggers (TriggerKind in src/campaign_doc.rs).
• New block kinds need: the Block/Val variant, template/kind_name, palette entry, checking (blocks::check, vars_set), execution in mscript.rs (exec/run_thread/eval), nesting in list_at (mscript) and list_mut (blocks_ui) if it has a body, the editor fields in blocks_ui.rs, blk.* texts in every language file, and a test.
• Side numbers: -1 any, 0 player, 1 heroes, 2 Mossgrim, 3 Lady Nightwell, 4 rival 3.
• Unknown creature names, zones, triggers and unset variables are reported by blocks::check.
• Reference: docs/CAMPAIGN_EDITOR.md and docs/MISSION_SCRIPTING.md.

Deployment policy

Deployment is not part of every change. Deploy only after tests pass and after the user explicitly asks for deployment or approves deployment.

When a deployable point is reached, ask the user whether deployment should be performed and then wait for the user's response. Do not deploy after asking unless the user confirms.

When asking for deployment approval, briefly explain what changed and what the user should test after deployment, if manual testing is needed. Examples include campaign editor script prompts, custom mission spawn actions, debug overlays, browser/WASM behavior, touch/menu behavior, or multiplayer-related flows when those areas changed.

A deployment always includes a push: the version bump commit (and any other finished commits) must be pushed to origin main before or together with the deploy. Never deploy unpushed code.

The usual deployment flow is:

python3 tools/bump_version.py
git add ...
git commit -m "..."
git push origin main
docker compose up -d --build

If the user only says weiter, continue implementation and commit/push the completed implementation step. Do not deploy unless explicitly requested.