Here you go:
# ASCII RPG
This repo uses Rust + Bevy (0.16.1), multi-crate workspace, RON assets, and a custom ASCII UI. The rules below keep contributions consistent, testable, and verifiable.
## Quick rules (read me first)
- Read/update CURRENT_TASK.md each step; delete when done.
- Build/lint/test (fish): cargo check --workspace; and cargo clippy --workspace --all-targets -- -D warnings; and cargo test --workspace
- Run dev tools: asset-editor/dev.fish; debug via /tmp/ascii_rpg_debug; prefer debug scripts in repo root.
- Logging: use info!/debug!/warn!/error! (no println!); avoid per-frame logs unless trace!.
- ECS: prefer components over resource maps; use markers + Changed; keep resources for config/assets only.
- UI: adaptive content; builder pattern; size-aware components.
- Done = compiles clean (clippy -D warnings), tests pass, verified in-app, no TODOs/hacks.
- If blocked: state why and propose the next viable step.
- Before large refactors/features: give 2–3 options and trade-offs; confirm direction before coding.
## 1) Build, lint, test (quality gates)
- Fish shell one-liner:
- cargo check --workspace; and cargo clippy --workspace --all-targets -- -D warnings; and cargo test --workspace
- Fix all warnings. Use snake_case for functions/files, PascalCase for types.
- Prefer inline rustdoc (///) and unit tests over standalone docs.
## 2) Run and debug (dev loop)
- Start the app with debug flags and use the command pipe at /tmp/ascii_rpg_debug.
- Quick start (fish):
- cargo run --bin app -- --skip-main-menu > debug.log 2>&1 &
- echo "debug viewport 0 0" > /tmp/ascii_rpg_debug
- echo "ui 30 15" > /tmp/ascii_rpg_debug
- Helper scripts at repo root:
- ./debug.sh, ./debug_keyboard.sh, ./debug_click.sh, ./debug_world.sh
- Logging rules:
- Use info!/debug!/warn!/error! (never println!).
- Don’t log per-frame unless trace!.
- Use tail/grep to keep logs readable.
## 3) Testing priorities
1) Unit tests first (small, deterministic outputs).
2) Manual testing while iterating.
3) End-to-end verification using the debug system.
4) UI changes require visual confirmation from the user.
## 4) Architecture guardrails
- ECS: Components (data), Systems (logic), Resources (global), Events (comm).
- Principles:
- Prefer components over resource maps. Avoid HashMap in resources.
- Optimize queries: marker components (e.g., IsOnCurrentMap), Changed.
- Separate concerns: tagging vs rendering vs gameplay.
- Resources only for config/assets; not entity collections/relationships.
- UI: Adaptive content, builder pattern, size-aware components.
- Code layout: lib/ui (components/builders), engine/src/frontend (UI systems), engine/src/backend (game logic).
## 5) Completion criteria (definition of done)
- All crates compile with no warnings (clippy -D warnings).
- All tests pass. Add/adjust tests when behavior changes.
- Feature is verified in the running app (use debug tools/logs).
- No temporary workarounds or TODOs left in production paths.
- Code follows project standards above.
## 6) Never-give-up policy
- Don’t mark complete with failing builds/tests or known issues.
- Don’t swap in placeholder hacks and call it “done”.
- If truly blocked, state why and propose a viable next step.
## 7) Debug commands (reference)
- Pipe to /tmp/ascii_rpg_debug:
- debug [viewport X Y] [full]
- move KEYCODE (Arrow keys, Numpad1–9, Space, Period)
- click X Y [left|right|middle]
- ui X Y
- Coordinates: y=0 at bottom; higher y = higher on screen.
- UI debug output lists text top-to-bottom by visual position.
## 8) Dev convenience (asset editor)
- Combined dev script:
- ./asset-editor/dev.fish (starts backend in watch mode + Vite dev)
- Frontend only:
- ./asset-editor/start-frontend.fish
## 9) Tech snapshot
- Rust nightly (rust-toolchain.toml), Bevy 0.16.1.
- Workspace layout: apps/ (game + editors), engine/ (frontend/backend), lib/ (shared), asset-editor/.
Keep changes small, tested, and instrumented. When in doubt: write a unit test, run the app, and verify via the debug pipe/logs.
## 10) Design-first for large changes
- When to do this: large refactors, cross-crate changes, complex features, public API changes.
- Deliverable (in CURRENT_TASK.md):
- Problem and goals (constraints, assumptions).
- 2–3 candidate approaches with pros/cons, risks, and impact.
- Chosen approach and why; edge cases; test plan; rollout/rollback.
- Keep it short (5–10 bullets). Get confirmation before heavy edits.