161 lines
6.4 KiB
Markdown
161 lines
6.4 KiB
Markdown
# 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/` and `ios/` 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/` or `ios/` are restored or generated
|
|
|
|
## Install
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm run web
|
|
```
|
|
|
|
Starts the Vite browser app on `http://127.0.0.1:5173`.
|
|
|
|
```bash
|
|
npm run dev:toolkit
|
|
```
|
|
|
|
Starts the local Toolkit socket server on `http://127.0.0.1:5175`.
|
|
|
|
```bash
|
|
npm run dev:all
|
|
```
|
|
|
|
Starts both the Vite app and Toolkit socket server.
|
|
|
|
```bash
|
|
npm run dev:clear
|
|
```
|
|
|
|
Attempts to stop the related local dev processes if a previous run hangs.
|
|
|
|
## Build Commands
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
curl http://bone-kingdom.tabitha.tealthrone/health
|
|
curl http://bone-kingdom.tabitha.tealthrone:5174/health
|
|
```
|
|
|
|
For a manual shared-socket restart on the host:
|
|
|
|
```bash
|
|
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.
|