BE3 project

You are inside of an ubuntu VM. You may install / remove programs as needed. If the disk runs out of space, you may free up space.

Guides:

• guides/adding_a_block.md
• guides/adding_a_game.md
• guides/adding_a_plugin_editor.md
• guides/beui.md
• guides/beui_keyboard.md
• guides/pan_and_zoom.md
• guides/reactive.md
• guides/testing_a_gui.md
• guides/the_new_block_stack.md

Do not:

• When making changes to serialization formats or network requests, do not consider backwards compatibility with existing clients or data. The project is still early, and it is fine to ask the user to delete all their data. The crash handler in block-app will offer this automatically.
• Do not use unicode symbols for icons, either use an icon library or no icon at all.
• Do not edit README.md. If it is out of date, you may say so in your handoff message.
• Don't use worktrees. If using subagents, run them sequentially rather than in parallel.
• Do not create routines. Do not subscribe to PRs. Do not set check-in timers.

Verification:

• ./scripts/check: Use this for fast compile feedback. It prepares non-Cargo prerequisites and checks the complete workspace with the feature unification the project expects. Prefer this over cargo build or cargo check directly.
• ./scripts/verify: This is the primary full check and is required before committing. Run it after coherent changes and use a 10 minute timeout in the tool call arguments so it is less likely to convert itself to a background task.
  • Run it in the foreground. This VM is suspended between turns, so a verify run sent to the background silently stalls and starts over. If a whole run does not fit in one tool call, run its three parts one after another instead: ./scripts/verify --lint, ./scripts/verify --tests, ./scripts/verify --plugin-tests. Together they are the same run.
  • This will run all project tests and clippy lints
  • A plugin's own tests are not part of the workspace run: they are compiled to wasm and run through the plugin host by scripts/internal/test-plugins.sh, which verify calls for you. block-editor-plugin is in that run too, because the guest half of the plugin framework only exists on wasm. Run that script on its own for faster feedback on one editor (scripts/internal/test-plugins.sh -p checklist); it takes cargo nextest run's arguments.
  • It will autofix formatting, clippy fixable rules, and it will autofix to enforce project-specific rules: It will delete all code comments & doc comments, it will structure test folders & files to the project's one test per file standard, it will automatically move+rename mod.rs files to be in the parent folder named after the folder instead, and it will format the bodies of view! macro calls (rustfmt cannot, because the body is not Rust syntax).
• ./scripts/build --target android: run this for changes that affect features specific to Android.
• ./scripts/build --target web: run this for changes that affect features specific to web.
• ./scripts/run --smoke: run this for changes that could affect native startup or runtime integration. It performs a bounded automated launch in a virtual display with isolated data.

Do:

• Use commit message format type: message. Include Co-Authored-By: (model name).
• When done, create a pull request on github for the change. Do not watch the pull request and do not check in on its status.
• In your handoff message, mention any small issues you encountered or small things you noticed that could make the code / application better.
• If you don't need tests in your search results, consider grep --exclude-dir="tests"
• If you find yourself polling waiting for a command to finish, run ./scripts/nopoll in the foreground

Design principles:

• if a request appears to violate one of these, confirm using the question tool. do not edit this list.
• general:
  • we should never be sleeping in a test. if we need to wait for something, we need to find a way to wait for it without sleeping.
• beui:
  • beui is a retained-mode ui that you interact with using a solidjs-like reactive framework.
  • beui layout is O(n) or better on the number of nodes in the tree.
  • beui is a reactive framework; we should push changes, not poll for changes.
• block-app plugins:
  • the plugin protocol is framework-independent. we theoretically could use it with different GUI frameworks without modifying the plugin protocol.
  • the plugin protocol passes textures without them leaving the GPU.