ShinobiX
ShinobiX is a browser-based ninja MMORPG. You build one shinobi over months —
training stats and jutsu rather than grinding XP, taking missions and hunts,
joining a clan, raising companions, and fighting AP-based tactical battles where
positioning, chakra and cooldowns decide the turn. Combat, rewards and saves are
resolved on the server, not in the browser.
It runs live, in the open, with real player saves. The client presents itself as
Shinobi Journey; the repository and backend package keep the ShinobiX
name.
Why Star This Repo
This is a live game's actual codebase, not a demo or a landing page: a React 19
client, an Express/Supabase backend, server-authoritative reward and anti-cheat
paths, and more than 10,000 automated tests covering combat, missions, economy,
PvP, saves, pets, towers, village systems and the release gates themselves.
If you are here to read rather than to play, the interesting parts are
api/_lock.ts (shared-state read-modify-write), the mint-token reward pattern
in docs/auth-and-anti-cheat-patterns.md,
and server.ts, where every route is registered by hand on purpose.
Gameplay
- Create a shinobi with a village, starter bloodline, avatar, jutsu kit, and
protected save.
- Train stats and jutsu, take missions and hunts, manage inventory, recover at
the hospital, and build long-term progression through the Logbook.
- Fight with AP-based tactical combat, movement, jutsu, weapons, consumables,
effects, cooldowns, battle logs, and server-validated reward paths.
- Join social and competitive systems including clans, ranked PvP, pet arena,
battle towers, card clash, village leadership, and sector-war foundations.
- Operate the live beta safely with emergency controls, audit logs, receipts,
rate limits, product metrics, and admin diagnostics.
Screenshots
| Academy Gate | Four rival villages |
|---|
| |
| Starter bloodlines | Story chronicles |
| |
Refresh these with npm run capture:screenshots --prefix shinobij.client -- <url>
against a running client. In-game shots past character creation need an account,
so they are still captured by hand - see docs/MEDIA_KIT.md.
Current Status
ShinobiX is a live public beta, not a 1.0 release. Its shipped player systems
include the complete early loop plus PvP and Ranked, Towers and Spire, Hollow
Gate, companions and their battle modes, Chronicle Showdown, the Celestial Tower
campaigns, clans and Clan Boss Operations, Village and Sector War, professions,
Legacy, Hall of Legends, and the village story chronicles.
Every system above has a kill switch, because a live game needs one. A feature
having an emergency disable does not mean it is unreleased — the switches exist
for incident response, and the systems are shipped.
All shipped Solo PvE combat modes now seal player loadouts, resolve actions,
recover sessions, and settle rewards on the server. The server rejects the
retired Weekly Boss client-damage and legacy mission-win report paths.
See the canonical Live Product Status. The
Public Beta Launch Recommendation and
Feature Flag Release Matrix are preserved as
historical rollout evidence.
Tech Stack
- Backend: Node 24, Express 5, TypeScript, Supabase/Postgres, Socket.IO.
- Client: React 19, Vite 8, TypeScript, Three.js, React Three Fiber.
- Operations: Railway deployment notes, health checks, release flags,
audit logs, Sentry integration, and build-size checks.
- Testing: Node test runner plus TypeScript/tsx tests across API modules,
combat engines, economy, PvP, missions, pets, towers, village systems, and
client libraries.
Quick Start
Requires Node.js 24 or newer. The exact version is pinned in .nvmrc (currently 24.21.0) — every CI workflow and the Dockerfile follow it, so a version manager that reads .nvmrc gives you exactly what CI and Railway run.
npm ci
npm test
Run the lightweight UI/mock client:
cd shinobij.client
npm ci
npm run dev
Vite starts on port 50891 by default (override with DEV_SERVER_PORT; HTTPS
when a local development certificate is available):
https://127.0.0.1:50891/
This Vite server intentionally implements only a small mock API for UI work. It
is not the authoritative game backend, so deeper missions, PvP, persistence,
training, and settlement routes may be unavailable there.
For a full local gameplay/QA server without a production database, build first,
then start the Express server in guarded in-memory test mode. In PowerShell:
npm run build
$env:NODE_ENV = "test"
$env:SHINOBIX_QA_MEMORY_KV = "1"
$env:SESSION_SECRET = "local-qa-session-secret-at-least-32-characters"
$env:ADMIN_PASSWORD = "local-qa-admin-password"
$env:DISABLE_SCHEDULED_JOBS = "1"
$env:DISABLE_SNAPSHOT_CRON = "1"
node dist/server.js
Open http://127.0.0.1:3000/. The in-memory backend refuses to start unless
NODE_ENV=test, so it cannot be reached in production; persistent production
operation still requires the database variables documented in .env.example.
Build everything:
npm run build
The full build compiles the server, builds the client, verifies the deployment
bundle, and runs the build-size check.
Project Layout
server.ts - the Express entry point. It imports every api/** handler and
registers each one explicitly, then serves the client build on the same port.
There is no folder-convention routing: an unregistered handler is unreachable.api/ - gameplay APIs, combat systems, storage, auth, rewards, telemetry,
realtime helpers, and beta hardening. Underscore-prefixed files here are
shared helpers, not routes.shared/ - code used by both the server and the client.shinobij.client/ - Vite/React game client.supabase-migrations/ - SQL migrations for the Postgres schema.scripts/ - catalog validation, asset helpers, release checks, simulations,
and build tooling.release-audit/ - standalone release verification programs.tools/ - developer utilities.docs/ - architecture plans, release audits, balance notes, and roadmap.
dist/ is generated, gitignored, and deliberately not committed - Railway
rebuilds it from source on every deploy.
Documentation
Only six markdown files live at the repo root, and each is load-bearing:
this README, CLAUDE.md (conventions and hard rules),
RELEASE_CHECKLIST.md,
FEATURE_FLAG_RELEASE_MATRIX.md,
RAILWAY_SETUP.md, and
PUBLIC_BETA_LAUNCH_RECOMMENDATION.md.
Everything else is under docs/. The one file to trust about what is actually
live is docs/LIVE_PRODUCT_STATUS.md — where a
dated audit disagrees with it, that file wins.
docs/archive/ holds point-in-time snapshots kept only for the
audit trail. Nothing in there describes how the system works today, and it is
safe to ignore.
Roadmap
The public roadmap is in docs/ROADMAP.md. Current work focuses
on coherence, player guidance, safety, observability, and live-beta polish.
Release Notes
Tagged snapshots and their notes are on
GitHub Releases. The current one
is v0.2.0-beta,
tagged 2026-09-14. Historical draft notes for the first beta are in
docs/RELEASE_NOTES_v0.1.0-beta.md.
Media Kit
Repository screenshots and capture notes live in
docs/MEDIA_KIT.md. Every image on this page is a real app
screen, captured from the running client rather than mocked up.
Security
Please report vulnerabilities privately, not in a public issue: use
private vulnerability reporting.
The full policy - what is in scope, what is not, and the rules that keep testing
away from other players' saves - is in
.github/SECURITY.md.
This is a live game with real player accounts, so please read the testing rules
before probing anything.
Contributing
ShinobiX is a solo-maintained live project rather than an open contribution
model, so there is no roadmap commitment on outside pull requests. Bug reports
are genuinely useful and welcome - open an issue with what you did, what
happened, and what you expected. Anything security-related goes through the
private channel above instead.
Two conventions matter if you do run the code locally: the root npm test is
Node's test runner and never opens a browser, and any change to a screen or
component also needs the Playwright suites in shinobij.client/. Both are
described in CLAUDE.md.
Community
License
Source-available, not open source — see LICENSE.
The source is published so it can be read and studied. Copying, redistributing,
hosting an instance, or reusing the artwork, audio, story content or names
requires written permission. Bundled third-party components (the Inter,
Marcellus and Roboto fonts, and one CC0 base mesh) stay under their own
licenses, which the LICENSE file points at.
