by p1necone | 2025-08-20 06:21:19+00:00
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<T>; 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<Entity, _> in resources. - Optimize queries: marker components (e.g., IsOnCurrentMap), Changed<T>. - 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.