102 lines
4.9 KiB
Markdown
102 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
cargo check --all-targets
|
|
cargo test
|
|
```
|
|
|
|
For changes that must remain runnable in the browser, also run:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
- Blocks are translated into Rhai internally and run by `src/mscript.rs` inside the fixed simulation step (deterministic, co-op safe).
|
|
- The Rust Rhai dependency must keep `no_time` enabled in `Cargo.toml` so the WASM output stays loadable by the macroquad JS bundle.
|
|
- Rhai reserves `spawn`; the internal API uses `spawn_unit`.
|
|
- 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, Rhai translation, the API function in `mscript.rs`, 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:
|
|
|
|
```bash
|
|
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.
|