Throne of the Bone King
React Native game shell for the Bone Lord Bob universe. The current app shares one React Native UI layer across browser, Electron, and future native mobile targets.
The project is in early development. The main working surface is a landscape-first menu and toolkit scaffold with persisted settings, route persistence, background music, policy/credits pages, and a browser-only Toolkit backed by a local Socket.IO server.
Current Targets
- Browser: Vite + React Native Web at
http://127.0.0.1:5173 - Electron: Vite renderer plus compiled Electron main/preload files
- Native mobile: React Native 0.85.3 source is present, but
android/andios/are not currently in this checkout - Toolkit: browser-only support surface gated by the Browser resolution setting and an active socket connection
Requirements
- Node
>=22.12.0 - npm
- Native mobile toolchains only when
android/orios/are restored or generated
Install
npm install
Development
npm run web
Starts the Vite browser app on http://127.0.0.1:5173.
npm run dev:toolkit
Starts the local Toolkit socket server on http://127.0.0.1:5175.
npm run dev:all
Starts both the Vite app and Toolkit socket server.
npm run dev:clear
Attempts to stop the related local dev processes if a previous run hangs.
Build Commands
npm run web:build
npm run web:preview
npm run electron:build
npm run electron:dev
npm run electron:package
electron:build builds the web renderer into dist/renderer/ and compiles Electron process files into dist/electron/.
Validation
npm run lint
npm run test -- --runInBand
npm run web:build
npm run electron:build
Husky increments the patch build version with npm run version:bump-build, writes public build metadata to .env, then runs npm run validate:commit on commit. Validation runs lint, Jest, and the Electron build path. The menu build label uses version-yyyymmdd-last7commit.
Before committing or pushing meaningful work, update src/data/toolkit/changelog.json with a concise release-ledger entry for the deliverable. Husky updates build metadata automatically, but changelog content is intentionally written by the developer or agent so the in-app Change Log stays useful.
App Structure
App.tsx # Safe area, status bar, viewport, navigator root
src/navigation/ # Route metadata and lightweight app-state navigator
src/screens/ # Home, Gameplay, Saves, Settings, Policies, Toolkit, generic pages
src/components/ # Shared React Native UI primitives
src/state/ # Zustand stores and persistence adapters
src/settings/ # Resolution and audio setting definitions
src/hooks/ # Background music and socket connection hooks
src/socket/ # Browser client for Toolkit socket content sync
socket/ # Local Socket.IO Toolkit server
src/data/ # Canonical editable JSON content, typed exports, and Toolkit seed data
src/assets/ # Images, fonts, music, and SCSS entrypoints
electron/ # Electron main and preload source
State and Persistence
The app uses Zustand. Route state, game settings, and Toolkit content state are separate stores.
- Native persistence adapter:
src/state/persistStorage.ts - Web/Electron persistence adapter:
src/state/persistStorage.web.ts - Shared persist helper:
src/state/createPersistOptions.ts - Game settings persist key:
blb-game-settings - Navigation persist key:
blb-navigation
Game settings currently include:
- resolution:
browser,iphoneMini,iphoneDefault,androidDefault,phoneLarge - autosave
- audio mute
- master, music, ambience, speech, and SFX volume
Toolkit
Toolkit access is intentionally limited:
- resolution must be set to
Browser - socket status must be connected
- socket server runs with
npm run dev:toolkit
The Toolkit contains socket-backed structured forms for volatile gameplay systems, Credits, Images, and Audio. JSON content is sourced from src/data/toolkit/ and synchronized through socket events for read, save, change broadcast, and refresh recovery. Audio and image uploads are written by the Toolkit socket into src/assets/music/uploads/ and src/assets/images/uploads/, then referenced by the record fileName field. Toolkit seed data and app content are exported through src/data/index.ts with interfaces from src/data/types/.
Socket health check:
curl http://127.0.0.1:5175/health
Shared Deploy Toolkit Socket
The hosted browser app at http://bone-kingdom.tabitha.tealthrone/ is built with VITE_TOOLKIT_SOCKET_URL=http://bone-kingdom.tabitha.tealthrone:5174. That socket is intentionally restarted from the shared repo workspace instead of from dist/, so Toolkit edits made by another person update the development JSON and upload folders directly:
- JSON content:
src/data/toolkit/ - Uploaded images:
src/assets/images/uploads/ - Uploaded audio:
src/assets/music/uploads/
Woodpecker deploys the static renderer, restarts the shared Toolkit socket with scripts/deploy/restart-toolkit-socket.sh, and validates both:
curl http://bone-kingdom.tabitha.tealthrone/health
curl http://bone-kingdom.tabitha.tealthrone:5174/health
For a manual shared-socket restart on the host:
TOOLKIT_SOCKET_HOST=0.0.0.0 npm run deploy:toolkit
Assets
Image assets live in src/assets/images/. Fonts live in src/assets/fonts/. Music lives in src/assets/music/. Browser SCSS builders live in src/assets/scss/.
src/assets/scss/index.scss is the only browser SCSS entrypoint. Builder partials separate tokens, mixins, globals, scrollbars, typography, layout, surfaces, buttons, forms, and Toolkit-specific class systems. Browser-only UI should reference reusable .blb-* classes from those builders instead of adding ad hoc CSS in feature files.
The browser favicon is src/assets/images/favicon.svg.
Native Mobile Notes
The shared UI is React Native and should remain native-compatible. Do not introduce DOM APIs into shared src/ code. Browser-only APIs belong in .web.ts files or src/web/.
When native folders are restored, native dependency setup such as CocoaPods should be handled in the platform folders at that time.