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.
• Campaign editor scripts live mainly in src/campaign_doc.rs and src/script.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 script language: Rhai.
• The Rust Rhai dependency must keep no_time enabled in Cargo.toml so the WASM output stays loadable by the macroquad JS bundle.
• Current implemented runtime hook: on_start(m).
• Current implemented script actions:
  • m.log(text)
  • m.objective(text)
  • m.spawn_at(side, kind, x, y, count, level)
  • m.spawn_count_in_zone(zone, kind, count, side, level)
  • m.spawn_wave(count)
• Rhai reserves spawn, so mission scripts use spawn_at for direct spawns.
• Side names currently accepted in script helper calls:
  • "PLAYER" or side 0
  • "HEROES" or side 1
  • "MOSSGRIM" or side 2
  • "NIGHTWELL" or side 3
  • "RIVAL3" or side 4
• Unknown creature names and unknown zone names should be rejected during script validation.

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.