Neptune.js

🌟 v3.4.0 Release Showcase: 🎮 Play Live Demo | 📖 Systems Showcase Tutorial | 📦 GitHub Release 3.4.0

A modular JavaScript 2D game engine with an entity-component architecture and a separate visual editor, Triton. Games run in the browser using Canvas 2D; Triton uses React, TypeScript, and Tauri for desktop authoring. MIT licensed.

The current goal is to finish a coherent 2D engine and prove it with a small playable action-RPG demo. 3D and multiplayer are outside this delivery. Existing modules and passing individual tests do not mean that the complete ARPG workflow is finished.

The user's final product scope is now locked in release one scope, based on the supplied 2.5D ARPG SRS. It retains 2D simulation and the existing architecture, while explicitly adding elevation, WebGL2 presentation, lighting, streamed worlds and integrated simulation/NPC/narrative authoring. That contract controls future feature scope; this README's capability statements describe what exists today.

Development setup

Use Node.js 24 LTS and Yarn Classic 1.22.x. Install from the committed lockfiles:

npm ci --ignore-scripts --no-audit --no-fund
yarn --cwd triton install --frozen-lockfile
npx playwright install chromium

On Linux, Playwright may also require its OS dependencies (npx playwright install --with-deps chromium). Browser tests require Chromium; do not skip them to obtain a passing result.

Run the sample from the repository root:

npm run serve

Open http://127.0.0.1:8000/debug_project/ and select Play Game. This preview server binds to localhost only and needs no Python installation. Use npm run serve -- --port 8001 to choose another port. ES module examples must be served over HTTP rather than opened as local files.

The Emberfall project includes the original ruins starter and an expanded expedition. Open http://127.0.0.1:8000/examples/emberfall/adventure.html for the expedition's title menu, connected hollow/keep rooms, three guarded seals, phased boss, ending and Continue flow. The original starter remains at http://127.0.0.1:8000/examples/emberfall/. In Triton, open the project and then scenes/expedition.scene to play the expedition. It is a bounded playable demo; the 10–15 minute fresh-player quality target remains unverified.

On Windows, double-click Neptune.cmd to start the desktop editor (yarn --cwd triton tauri dev). The launcher uses installed tools or the optional sibling DevTools folder.

Run Triton's frontend with npm run dev:editor. This previews the UI; native filesystem operations require the desktop app. For that, install the Tauri prerequisites (on Windows: Rust MSVC toolchain, Microsoft C++ Build Tools/Windows SDK, and WebView2), then run npm run dev.

Verify a change

npm test
npm run build:editor
npm run lint:editor
npm run docs
npm run test:docs-contract

npm test runs the existing legacy engine harness, runtime/editor integration suites, and browser checks in sequence, stopping at a failed batch. npm run test:engine runs only the first harness; it is not a substitute for the full suite. The batch list lives in scripts/test.js.

Documentation generation refreshes generated HTML in docs/ while preserving authored Markdown guides and tutorials. Inspect generated changes separately from source edits. Native editor changes also need native verification; browser tests with Tauri command stubs do not establish real filesystem behavior. cargo check --locked --manifest-path triton/src-tauri/Cargo.toml checks native compilation prerequisites and code without packaging a release.

Architecture and repository map

Keep the entity-component structure. An Entity owns components and children; Transform describes its 2D placement; Scene and SceneManager organize worlds; Behaviour supplies game lifecycle callbacks. Use public add/remove/destroy paths so scripts and runtime state are cleaned up correctly.

PathResponsibility
src/core/Application loop, entities, scenes, component registry, loading, saves and clock
src/components/, src/scripts/Components, transforms, authoring components and behaviours
src/rendering/, src/ui/, src/input/, src/audio/, src/math/Canvas rendering, UI/HTML bridge, input, audio and 2D math
src/titan/Animation, poses and rigs
src/thalassa/Tilemaps, tilesets, navigation, cameras and feedback
src/nereid/Bodies, colliders, interactions and physics helpers
src/larissa/Combat, enemies/bosses, stats, progression and inventory
src/galatea/Dialogue and cutscenes
src/neptune.jsBrowser entry and exports; importing it currently creates the shared application
triton/src/, triton/src-tauri/Editor UI and native backend; not game-runtime dependencies
debug_project/, examples/Integrated sample and small task-oriented examples
tests/, triton/tests/Engine, integration and browser checks
scripts/, static/, docs/Contributor tools, JSDoc source/tutorials and generated/authored documentation

Do not rename public modules or move runtime files solely for tidiness: games and saved resources can depend on those paths. Improve a module in place unless a migration is explicitly part of the change.

Current capability and limits

The codebase includes scene/entity serialization, Canvas 2D rendering, cameras/layers, tilemaps and minimum-cost grid navigation, animation, collision and trigger helpers, configurable combat and enemy AI, RPG progression/inventory, dialogue, audio, HTML UI, save/load, and editor authoring/persistence. See the tutorials for actual entry points and examples.

ProjectBehaviour loads project-local gameplay modules in both the browser runtime and Triton Game View, without importing editor code into games. See Emberfall for its module/settings format and lifecycle contract. KeyboardInput.IsKeyPressed preserves quick taps until frame clear; focus loss clears held keys. Native opening, transform editing, save/reopen, activation, movement, gameplay saves and playback were exercised against the actual Windows editor; see workflow evidence.

Important remaining integration work:

  • New ARPG code uses Combatant for authoritative health; Stats.bindCombatant() provides an explicit legacy health view. Standalone Stats and other RPG-stat integration still require deliberate ownership.
  • Nereid.TopDownController moves in world units using Nereid solids and the centered BoxCollider adapter. Legacy platformer and collision APIs remain available; this does not make them interchangeable.
  • Action-based keyboard input, bounded fixed simulation steps and authored-state restoration after Game View Stop are implemented. Gamepad input, broader rebinding UI and a completed multi-map game remain planned.
  • The public browser entry performs DOM/application initialization on import. Make any future bootstrap changes compatible and explicit.
  • Tile rendering scans map cells, collision checks pairs, and some AI lookups scan occupants. Measure real workloads and optimize demonstrated limits; there is no established large-crowd FPS guarantee.

The locked scope controls release requirements. The earlier product contract and performance budgets provide historical context and workload guidance where consistent with that scope. Historical native observations are in M12 acceptance evidence; they are not verification of the current machine or a new release.

TODO / next delivery

November 19 delivery: scene edit history, the world grid, context commands, functional component authoring, authored HTML UI preview and opt-in editor tools are implemented alongside runtime foundations and the playable expedition. The reported nested-child overlay offset is fixed. See delivery evidence and limits. These changes do not close the broader engine/editor/game roadmap.

Active task queue: release-one implementation plan. It groups the locked S01-S17 scope into tasks with acceptance criteria, edge-case tests, ownership rules and prerequisites. The older roadmap retains historical evidence; its content-length targets and estimates do not control this release.

SystemTask IDs
Core lifecycle, timing, facts, rules and project modulesCORE-01 through CORE-04
Input and device mappingsINPUT-01 through INPUT-03
Nereid physics and spatial queriesPHYS-01 through PHYS-04
Thalassa world/chunks and navigationWORLD-01 through WORLD-03; NAV-01 through NAV-03
Rendering and cameraRENDER-01 through RENDER-04
Lighting, particles and weatherFX-01 through FX-03
Assets and Titan animationASSET-01/02; ANIM-01
Proteus sound/musicAUDIO-01 through AUDIO-03
Larissa combat and RPGCOMBAT-01/02; RPG-01/02
Ability compositionABILITY-01/02
Local environmental simulationSIM-01 through SIM-03
NPC/enemy AIAI-01 through AI-03
Galatea dialogue, quests and cutscenesSTORY-01 through STORY-03
Game UI runtimeGUI-01 through GUI-03
Persistence and recoverySAVE-01 through SAVE-03
Triton authoringEDIT-01 through EDIT-06
Diagnostics, replay and measured optimizationQA-01/02; PERF-01/02
Export, packaging, templates and documentationSHIP-01 through SHIP-03
Integrated Emberfall and independent creator proofDEMO-01 through DEMO-03

Agent starting instructions: read AGENTS.md and the plan; inspect existing code/evidence; claim a task with exact files and dependencies; implement and run its behavioral checks; record results and remaining gaps. Queue items start Open / needs verification, not as claims that existing systems are absent. Shared contracts must be agreed before parallel dependent work.

Start with CORE contracts and existing runtime inconsistencies, then physics/spatial queries, world/navigation, combat and persistence. Rendering/assets/audio and later simulation/AI/story proceed where prerequisites and file ownership permit. Diagnostics and tests accompany every stage. Runtime work can precede new editor panels; authoring and native workflows still need their own acceptance.

The proof content is one village and adjacent dungeon, 10-20 NPCs, three enemy archetypes, three abilities, a phased boss, one branching quest, a fire/water interaction and an ending. A fresh creator must build a second village without engine changes. No playtime padding or inherited 30-60 minute requirement. See locked boundaries and end-to-end gates.

Tutorials

Contributing

The reusable Neptune.js skill stores project preferences, past corrections and the parallel TODO workflow. Its reference-driven design direction is compact dark neumorphism; preserve raised controls and inset fields. Keep the skill's dated context synchronized with verified changes.

The compact editor is checked at 125% browser scaling across 1024–1536px logical window widths. It starts maximized in a normal Windows window, preserves readable hierarchy/Inspector widths after layout restore, and reports live unsaved edits and file save activity. See the native and browser evidence; full nested-transform editing remains unfinished.

Read AGENTS.md for architecture boundaries and verification guidance. main is the integration branch; use short-lived codex/* or other focused feature branches. Keep changes reviewable and preserve unrelated work. Source/API readiness, native acceptance, and publishing are distinct outcomes.