deathstar

Stellar Abyss is a desktop-oriented, browser-run 3D space combat prototype built with Babylon.js, TypeScript and Vite. Ships, environment, universe and audio are described as original and procedural — the README explicitly states the project does not use protected ships, characters, logos, music or sound effects from existing franchises. **Story and setup** The game is framed as an original space-opera setting: a navigator exiled from the Order of the Threshold follows a signal into the Náris Belt, where an unnamed military force guards the passage home. At launch the player picks between two ships, the Arthur Comet and the Gael Ray. A reconnaissance flight escalates into battles against fighter squadrons and eventually the Obelisk, a large capital ship. **Controls and combat** Flight is mouse-steered, with distance from screen center controlling turn intensity; returning the mouse to center flies straight and pointer lock is not used. Keyboard bindings cover cruise speed (W/S), roll (A/D), strafe (Q/E), dual laser pulse (left mouse), plasma cannon after unlock (right mouse), energy rupture after unlock (R), boost with recharge (Left Shift), a dodge with brief invulnerability and a three-second cooldown (Space), target selection and cycling (F, Tab), pause (Esc), mute (M) and a diagnostics toggle (F3). Plasma deals area damage and energy rupture is a fast torpedo with an eight-second cooldown. The mission auto-pauses when the window loses focus. **Mission structure** Six stages progress from reconnaissance and intercepting scouts, through larger patrols and assault fighters, to unlocking the plasma cannon, facing elite fighters and unlocking energy rupture, thinning reinforcements, and finally dismantling the Obelisk subsystem by subsystem — defense turrets, shield generators, ion engines and reactor — followed by a chain reaction and mission completion. **Rules and feedback** Shields regenerate five seconds after taking damage, while hull integrity does not regenerate. Destroying a fighter restores seven shield points. Asteroids and the capital ship cause collision damage that is not an instant kill. A Test Flight option advances mission time at 4× speed while keeping movement, weapons, damage and cooldowns unchanged. **Interface and localization** The game starts in English and offers an EN / PT-BR selector in the menu and pause screen, with the choice persisted in the browser. Proper nouns from the setting remain untranslated. **Running and building** Local development requires Node.js 22.12+ or Node.js 24; the documented flow is `npm install` then `npm run dev`, serving on `http://127.0.0.1:5173`. Appending `?renderer=webgl&debug` forces WebGL2 and enables diagnostics. A production build can be served with `npm run build` and `npm run preview`. A GitHub Actions workflow in `.github/workflows/deploy.yml` builds and publishes `dist/` to GitHub Pages when `main` is pushed, and the README notes the workflow requests only the read, Pages write and deployment identity permissions GitHub Pages requires. **Architecture** The code is organized into modules including core (engine, loop, input, assets), player (flight and health), enemies (AI and formations), weapons (pooled projectiles and collision), world (space environment), effects, audio, progression, boss and ui. Gameplay constants live in `src/config.ts`; combat and progression tests are in `tests/` and a browser smoke test is in `scripts/`. `AssetManager.ship()` creates temporary primitive models, and `AssetManager.loadModel(url, parent)` loads glTF/GLB for future visual replacement. Models face local +Z and no external model is required to play. WebGPU is attempted first with automatic WebGL2 fallback. **Verification** The documented checks are `npm test`, `npm run build`, `npm run dev` and `node scripts/browser-smoke.mjs`. The smoke test needs a local server and Chrome and covers startup, acceleration, boost, steering while firing, real kills, pause, resume, restart and browser errors, writing screenshots to temporary paths. The README states six logic tests pass and that Chrome/WebGL2 validation confirmed firing, steering while firing, three kills with score, pause, resume, restart and no runtime errors, with a passing production build; it also notes that WebGPU and a full browser playthrough of the capital-ship battle were not validated in this environment. **Status and limitations** The prototype has one complete mission with victory, defeat and restart states. Ships and audio are described as functional procedural placeholders. Artistic textures, LODs, touch controls and gamepad controls are not implemented yet, and the main bundle is about 6.3 MB, or 1.38 MB gzip, with loading optimization pending. The stated target is 60 FPS on a reasonable desktop, with WebGL2 as the reference diagnostic path and local fallbacks for Google Fonts. Diagnostics can display FPS, position, speed, active enemies, projectiles, active meshes and mission time. **Contributing** Contributions are accepted via fork-and-pull-request against `jeffotoni/deathstar`; the README asks contributors not to push feature branches to the official repository, to use Conventional Commits, to keep unrelated refactors out of a PR, and to explain the player-facing result along with validation commands and a screenshot or recording for visual or gameplay changes. It also recommends protecting the `main` branch, keeping Actions permissions read-only by default, avoiding secrets in untrusted fork code, not committing credentials or generated build output, and reporting vulnerabilities privately per `SECURITY.md`.