2.5 KiB
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 athttp://localhost:4173.npm test: run the Node built-in test suite.npm run build: create a static deployment indist/.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.