🧭 darkmoon · Features · Roadmap · Tasks · Changelog · Metrics
3D browser combat game built with React 19, Three Fiber, Socket.io, and Vite. Solo mode with full combat gameplay is live; multiplayer is planned.
Live Demo: darkmoon.dev
- ARCHITECTURE.md: App boundaries, deployment, and contracts
- API.md: HTTP and WebSocket interface reference
[shipped]Combat Gameplay with AI Bots — Full deathmatch and CTF modes with bot LOS checks, weapon reload system (including timing-based precision snap mechanic), angular spread, bot jumping, tracer beams, hit direction indicators, score tension alerts, and ShotgunVFX cone particle effects.[shipped]Shooting Gallery Mode — Standalone target-practice mode with crosshair and bot tracer improvements.[shipped]Mouse-Aimed Firing & Player Reticle — Ground-plane raycast aiming with GPU-composited CSS crosshair overlay; velocity-based smooth movement with camera-relative A/D strafing.[shipped]Pluggable Game Mode Architecture —GameModeHandlerinterface decouples mode logic;TagMode(with health/damage support),DeathmatchMode, andCTFModeship as reference implementations.[shipped]Modular UI Architecture —GameUIandSolo.tsxfully componentized: 15 HUD sub-components, 3 new hooks (useGameStart,useBotPositionHandlers,useDebugModes), and a dedicateduseGameUIState.tsfor all event-driven state.[shipped]WebSocket Server Foundation — Socket.io and server validation are in place for future live modes.[in-progress]Multiplayer 3D Gameplay — Multiplayer foundations exist, but the deployed experience is still solo-first.[in-progress]Mobile Support — Responsive layout and touch controls exist, but device validation is still open.[shipped]Modern Tooling — Vite, Vitest (659 tests), ESLint, Prettier, TypeScript, and CI are wired into the repo.
# Dev server (hot reload via Vite)
docker compose -f config/docker-compose.yml up soloVisit http://localhost:4444. Solo mode is the only live experience; multiplayer is not yet available.
All checks run via Docker — no local Node.js required.
# Run all tests (659 tests, Vitest)
docker compose -f config/docker-compose.yml --project-name darkmoon --profile test run --rm test
# Lint
npm run lint:docker
# Production build
docker build --target runner -t darkmoon-prod .
docker run --rm -p 4444:4444 darkmoon-prodGit hooks are managed by husky and run Docker automatically:
- pre-commit: runs lint-staged via Docker (lint changed files)
- pre-push: runs full test suite in Docker
Install hooks after cloning:
npm install # triggers husky install via `prepare` scriptpre-commit (optional, adds basic file hygiene on top of husky):
pip install pre-commit && pre-commit installSee CONTRIBUTING.md (org default) for code quality standards and deployment tips.
Every doc at the repo root (other than this README) and under docs/ (the files mirrored into the Obsidian vault), so none of them is orphaned.
- Darkmoon API Reference —
docs/API.md - Darkmoon Architecture —
docs/ARCHITECTURE.md - Changelog —
docs/CHANGELOG.md - DARKMOON Features —
docs/FEATURES.md - Agent Pickup Instructions —
docs/INSTRUCTIONS.md - Metrics —
docs/METRICS.md - Roadmap —
docs/ROADMAP.md - Tasks —
docs/TASKS.md
docs/archive/
- Architecture Improvements - Quick Reference —
docs/archive/ARCHITECTURE_IMPROVEMENTS.md - Delivery Pipeline Handoff —
docs/archive/HANDOFF-player-tag-fix-20260403.md - L7 Engineering Review - Darkmoon —
docs/archive/L7_ENGINEERING_REVIEW.md - DARKMOON Product Roadmap —
docs/archive/ROADMAP_DETAILED.md
docs/projects/conkers/
- 🐿️ Conker's Bad Fur Day — Open Source Three.js Recreation Guide —
docs/projects/conkers/CONKER_BFD_BUILD_GUIDE.md - Tech Debt Tracker —
docs/projects/conkers/TECH_DEBT.md
docs/projects/multi/
- Multiplayer Readiness Gate —
docs/projects/multi/MULTIPLAYER_GATE.md - Multiplayer Shooter Roadmap — "Robot Conker's Bad Fur Day" —
docs/projects/multi/MULTIPLAYER_SHOOTER_ROADMAP.md
MIT © 2025 Nitsuah Labs
Inspiration: R3F.Multiplayer by @juniorxsound
Shared community policies are centralized in https://github.com/nitsuah/.github: