cabinw
10cf93a324
Add the paper direction with thin tracks, outlined hexagons and line arrows, without exterior color markers or piece numbers. Add a unified catalog for five designs and their 25 themes, with direct review links. Organize each design into an authored design.md, generated tokens.json and preview. Add Agent routing, shared integration guidance, a machine-readable manifest and an executable rendering example. Preserve legacy preview and document links. Validation: 16 focused design, theme and package tests passed; npm run design and static build passed. Confirmed all eight authored documents survive generation unchanged. Browser checks covered mobile, tablet and desktop layouts, theme links and migrated previews. Native engine integration and visual verification remain pending.
43 lines
3.6 KiB
Markdown
43 lines
3.6 KiB
Markdown
# Repository Guidelines
|
|
|
|
## Project Structure & Module Organization
|
|
|
|
HEX TRAILS is a dependency-free JavaScript hexagonal track puzzle. `index.html` and `style.css` define the responsive browser interface. Keep gameplay, solving, generation, validation, and difficulty scoring in `src/core.js`; coordinate conversion and curve sampling belong in `src/geometry.js`. `src/renderer.js` exposes engine-independent drawing commands plus the Canvas adapter. Browser controls and persistence live in `src/app.js`.
|
|
|
|
`levels/campaign.json` and generated `src/levels.js` contain the campaign. `tests/` holds Node tests, `scripts/` provides development utilities, and `docs/` explains design and portability. `cocos/HexTrailsBoard.ts` is the native engine adapter example.
|
|
|
|
## Build, Test, and Development Commands
|
|
|
|
Use Node.js 20 or newer. No dependency installation is required.
|
|
|
|
- `npm run dev`: serve the application at `http://localhost:4173`.
|
|
- `npm test`: run the Node built-in test suite.
|
|
- `npm run build`: create a static deployment in `dist/`.
|
|
- `npm run levels`: regenerate both campaign data files using deterministic seeds.
|
|
|
|
Open the application over HTTP because it uses ES modules. Do not commit `dist/` or `node_modules/`.
|
|
|
|
## Coding Style & Naming Conventions
|
|
|
|
Use ES modules, two-space indentation, camelCase functions, and PascalCase classes. No formatter or linter is configured. Follow surrounding conventions and avoid unrelated formatting changes. Keep DOM and storage APIs out of the model and geometry modules. Keep gameplay rendering portable: polygons, lines, circles, and PNG atlas sprites. Store generated art and prompts in `assets/`; source rectangles live in `src/sprites.js`. `src/path-math.js` shares geometry between rendering and swept collision detection.
|
|
|
|
## Testing Guidelines
|
|
|
|
Name tests `tests/*.test.js`. Cover rule changes with meaningful fixtures, particularly board rotation, swept collisions along curves, blockers, loops, undo, and malformed imports. Campaign changes must validate and solve completely. Test responsive gameplay and editor flows after interface changes. No coverage percentage is enforced.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
|
|
No Git history was available when this project was created. Use focused, imperative commit subjects. Describe behavior changes, link relevant issues, and include test results and screenshots for visual changes. State native-engine verification limits explicitly.
|
|
|
|
## Agent-Specific Instructions
|
|
|
|
Before calling MCP tools, read `/Users/wukaibing/.grok-go/agents-guide.md` for version-specific GrokGo instructions.
|
|
|
|
### Level-production scope
|
|
|
|
The user has explicitly limited this work to level creation: board layouts, track connections, pieces, difficulty, and level ordering. Use the game's existing interface and interaction logic. Do not independently add controls, hide controls, change layouts or themes, or introduce teaching-specific interface behavior. Any future interface or interaction change requires an explicit user request. Preserve existing campaign numbering and saved progress when integrating level data.
|
|
|
|
### Design-system entry point
|
|
|
|
For user-requested design/UI work, start at [design/README.md](design/README.md) and [design/AGENTS.md](design/AGENTS.md), then read [design/shared.md](design/shared.md) and the selected `design/directions/<id>/design.md`. [design/manifest.json](design/manifest.json) lists all five stable IDs, canonical documents, previews, and generated tokens. Each design has five themes; design IDs are separate from theme IDs and campaign versions. Authored design.md files must not be overwritten by generators. This entry point does not expand the scope of level-only tasks.
|