Toymoil

A highly customizable modular cute-tech toybox roguelite.

Toymoil is an early-stage Godot action roguelite about toybox chaos, modular weapons, room-local gadgets, and boss-born powers. It is built around highly customizable modular content, stable validation-friendly data, and an agent-first development workflow. The project is currently an architecture and content-pipeline seed, not a playable release.

Chinese version: README.CN.md

Status

This repository is public early so the architecture, validation rules, content contracts, and agent-first workflow can grow in the open.

• Engine: Godot 4.7+ desktop, Forward+ / Vulkan
• Language: GDScript-first
• Scope: 2.5D room-based dungeon roguelite
• Current focus: stable IDs, typed Resources, manifests, ContentDB, validation, presentation catalogs, modular content contracts, agent-friendly contribution workflow
• Not available yet: playable release, Workshop integration, external runtime content-pack loading, downloadable builds

Links

• Vision
• Game design
• Technical architecture
• Art pipeline
• Community content contract
• Agent contribution protocol
• Contributing
• Asset contributions
• Asset license boundary

Agents should start from AGENTS.md. CLAUDE.md points to the same instructions.

Contributing

Toymoil is designed as an agent-first, community-friendly open-source game project. Contributions should leave the repository more explicit, more validated, and easier for the next contributor to understand.

Good early contributions include:

• focused Godot architecture improvements
• validation and tooling that make contracts machine-checkable
• typed Resource definitions that fit the manifest/ContentDB path
• docs that clarify existing public contracts
• small final-form gameplay slices
• asset contributions with metadata, license/IP records, and Godot-ready handoff notes
• data/assets-only community content proposals

Please read CONTRIBUTING.md before opening a PR.

Building

Clone with submodules:

git clone --recurse-submodules https://github.com/Royalvice/Toymoil.git
cd Toymoil

If you already cloned without submodules:

git submodule update --init --recursive

Verify the Godot-visible GUT addon path:

python3 tools/bootstrap/setup_gut_addon.py --check

Open the repository root in Godot. project.godot lives at the root.

Validation

Run the checks relevant to your change:

python3 tools/content_pack/validate_pack.py --check
python3 tools/agent/validate_task_packet.py --check
python3 skills/prompt-regression-tests/scripts/test_skill_contracts.py
/Applications/Godot.app/Contents/MacOS/Godot --headless --path . -s res://game/editor_tools/command/run_validation.gd --json res://reports/validation/latest.json --markdown res://reports/validation/latest.md
/Applications/Godot.app/Contents/MacOS/Godot --headless --path . -s res://addons/gut/gut_cmdln.gd -gdir=res://tests -ginclude_subdirs -gexit
git diff --check

Do not claim a check passed unless you ran it. If a relevant check cannot run, explain why in the PR.

Troubleshooting

• If GUT commands fail because res://addons/gut is missing, run python3 tools/bootstrap/setup_gut_addon.py --check and then git submodule update --init --recursive.
• If Godot reports missing imports, open the project once in the editor or run the relevant headless command after the submodule/addon path is ready.
• If content-pack validation fails, start with docs/09_COMMUNITY_CONTENT.md and the schema under content/schema/.
• If an agent task is unclear, use docs/10_AGENT_CONTRIBUTION_PROTOCOL.md and the task packet schema under tools/agent/.

Feature Requests

Use GitHub Issues for focused bugs, tasks, and concrete proposals. Use GitHub Discussions for broader design/community conversation.

Please avoid requests for Workshop integration, arbitrary script mods, external pack scanning, or large future systems before the first playable slice is fun. The seams exist, but the first public phase is data/assets-only and validation-first.

License

Code is licensed under the GNU General Public License v3.0. See LICENSE.

Art assets, brand identity, AI-generation lineage, and metadata-controlled asset files are not automatically licensed for reuse under the code license. See ASSET_LICENSE.md for the asset boundary.