63 lines
1.9 KiB
Markdown
63 lines
1.9 KiB
Markdown
|
# Contributing to The Nexus
|
||
|
|
|
||
|
|
Thanks for contributing to Timmy's sovereign home. Please read this before opening a PR.
|
||
|
|
|
||
|
|
## Project Stack
|
||
|
|
|
||
|
|
- Vanilla JS ES modules, Three.js 0.183, no bundler
|
||
|
|
- Static files — no build step
|
||
|
|
- Import maps in `index.html` handle Three.js resolution
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
```
|
||
|
|
index.html # Entry point: HUD, chat panel, loading screen
|
||
|
|
style.css # Design system: dark space theme, holographic panels
|
||
|
|
app.js # Three.js scene, shaders, controls, game loop (~all logic)
|
||
|
|
```
|
||
|
|
|
||
|
|
Keep logic in `app.js`. Don't split without a good reason.
|
||
|
|
|
||
|
|
## Conventions
|
||
|
|
|
||
|
|
- **ES modules only** — no CommonJS, no bundler imports
|
||
|
|
- **Color palette** — defined in `NEXUS.colors` at the top of `app.js`; use it, don't hardcode colors
|
||
|
|
- **Conventional commits**: `feat:`, `fix:`, `refactor:`, `test:`, `chore:`
|
||
|
|
- **Branch naming**: `claude/issue-{N}` for agent work, `yourname/issue-{N}` for humans
|
||
|
|
- **One PR at a time** — wait for the merge-bot before opening the next
|
||
|
|
|
||
|
|
## Before You Submit
|
||
|
|
|
||
|
|
1. Run the JS syntax check:
|
||
|
|
```bash
|
||
|
|
node --check app.js
|
||
|
|
```
|
||
|
|
2. Validate `index.html` — it must be valid HTML
|
||
|
|
3. Keep JS files under 500 KB
|
||
|
|
4. Any `.json` files you add must parse cleanly
|
||
|
|
|
||
|
|
These are the same checks the merge-bot runs. Failing them will block your PR.
|
||
|
|
|
||
|
|
## Running Locally
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npx serve . -l 3000
|
||
|
|
# open http://localhost:3000
|
||
|
|
```
|
||
|
|
|
||
|
|
## PR Rules
|
||
|
|
|
||
|
|
- Base your branch on latest `main`
|
||
|
|
- Squash merge only
|
||
|
|
- **Do not merge manually** — the merge-bot handles merges
|
||
|
|
- If merge-bot comments "CONFLICT": rebase onto `main` and force-push your branch
|
||
|
|
- Include `Fixes #N` or `Refs #N` in your commit message
|
||
|
|
|
||
|
|
## Issue Ordering
|
||
|
|
|
||
|
|
The Nexus v1 issues are sequential — each builds on the last. Check the build order in [CLAUDE.md](CLAUDE.md) before starting work to avoid conflicts.
|
||
|
|
|
||
|
|
## Questions
|
||
|
|
|
||
|
|
Open an issue or reach out via the Timmy Terminal chat inside the Nexus.
|