feat(app): add browser toolkit support
This commit is contained in:
@@ -1,97 +1,135 @@
|
||||
This is a new [**React Native**](https://reactnative.dev) project, bootstrapped using [`@react-native-community/cli`](https://github.com/react-native-community/cli).
|
||||
# Throne of the Bone King
|
||||
|
||||
# Getting Started
|
||||
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.
|
||||
|
||||
> **Note**: Make sure you have completed the [Set Up Your Environment](https://reactnative.dev/docs/set-up-your-environment) guide before proceeding.
|
||||
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.
|
||||
|
||||
## Step 1: Start Metro
|
||||
## Current Targets
|
||||
|
||||
First, you will need to run **Metro**, the JavaScript build tool for React Native.
|
||||
- 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
|
||||
|
||||
To start the Metro dev server, run the following command from the root of your React Native project:
|
||||
## Requirements
|
||||
|
||||
```sh
|
||||
# Using npm
|
||||
npm start
|
||||
- Node `>=22.12.0`
|
||||
- npm
|
||||
- Native mobile toolchains only when `android/` or `ios/` are restored or generated
|
||||
|
||||
# OR using Yarn
|
||||
yarn start
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
## Step 2: Build and run your app
|
||||
## Development
|
||||
|
||||
With Metro running, open a new terminal window/pane from the root of your React Native project, and use one of the following commands to build and run your Android or iOS app:
|
||||
|
||||
### Android
|
||||
|
||||
```sh
|
||||
# Using npm
|
||||
npm run android
|
||||
|
||||
# OR using Yarn
|
||||
yarn android
|
||||
```bash
|
||||
npm run web
|
||||
```
|
||||
|
||||
### iOS
|
||||
Starts the Vite browser app on `http://127.0.0.1:5173`.
|
||||
|
||||
For iOS, remember to install CocoaPods dependencies (this only needs to be run on first clone or after updating native deps).
|
||||
|
||||
The first time you create a new project, run the Ruby bundler to install CocoaPods itself:
|
||||
|
||||
```sh
|
||||
bundle install
|
||||
```bash
|
||||
npm run dev:toolkit
|
||||
```
|
||||
|
||||
Then, and every time you update your native dependencies, run:
|
||||
Starts the local Toolkit socket server on `http://127.0.0.1:5174`.
|
||||
|
||||
```sh
|
||||
bundle exec pod install
|
||||
```bash
|
||||
npm run dev:all
|
||||
```
|
||||
|
||||
For more information, please visit [CocoaPods Getting Started guide](https://guides.cocoapods.org/using/getting-started.html).
|
||||
Starts both the Vite app and Toolkit socket server.
|
||||
|
||||
```sh
|
||||
# Using npm
|
||||
npm run ios
|
||||
|
||||
# OR using Yarn
|
||||
yarn ios
|
||||
```bash
|
||||
npm run dev:clear
|
||||
```
|
||||
|
||||
If everything is set up correctly, you should see your new app running in the Android Emulator, iOS Simulator, or your connected device.
|
||||
Attempts to stop the related local dev processes if a previous run hangs.
|
||||
|
||||
This is one way to run your app — you can also build it directly from Android Studio or Xcode.
|
||||
## Build Commands
|
||||
|
||||
## Step 3: Modify your app
|
||||
```bash
|
||||
npm run web:build
|
||||
npm run web:preview
|
||||
npm run electron:build
|
||||
npm run electron:dev
|
||||
npm run electron:package
|
||||
```
|
||||
|
||||
Now that you have successfully run the app, let's make changes!
|
||||
`electron:build` builds the web renderer into `dist/renderer/` and compiles Electron process files into `dist/electron/`.
|
||||
|
||||
Open `App.tsx` in your text editor of choice and make some changes. When you save, your app will automatically update and reflect these changes — this is powered by [Fast Refresh](https://reactnative.dev/docs/fast-refresh).
|
||||
## Validation
|
||||
|
||||
When you want to forcefully reload, for example to reset the state of your app, you can perform a full reload:
|
||||
```bash
|
||||
npm run lint
|
||||
npm run test -- --runInBand
|
||||
npm run web:build
|
||||
npm run electron:build
|
||||
```
|
||||
|
||||
- **Android**: Press the <kbd>R</kbd> key twice or select **"Reload"** from the **Dev Menu**, accessed via <kbd>Ctrl</kbd> + <kbd>M</kbd> (Windows/Linux) or <kbd>Cmd ⌘</kbd> + <kbd>M</kbd> (macOS).
|
||||
- **iOS**: Press <kbd>R</kbd> in iOS Simulator.
|
||||
Husky runs `npm run validate:commit` on commit. That command runs lint, Jest, and the Electron build path.
|
||||
|
||||
## Congratulations! :tada:
|
||||
## App Structure
|
||||
|
||||
You've successfully run and modified your React Native App. :partying_face:
|
||||
```text
|
||||
App.tsx # Safe area, status bar, viewport, navigator root
|
||||
src/navigation/ # Route metadata and lightweight app-state navigator
|
||||
src/screens/ # Home, 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 such as credits
|
||||
src/assets/ # Images, fonts, music, and SCSS entrypoints
|
||||
electron/ # Electron main and preload source
|
||||
```
|
||||
|
||||
### Now what?
|
||||
## State and Persistence
|
||||
|
||||
- If you want to add this new React Native code to an existing application, check out the [Integration guide](https://reactnative.dev/docs/integration-with-existing-apps).
|
||||
- If you're curious to learn more about React Native, check out the [docs](https://reactnative.dev/docs/getting-started).
|
||||
The app uses Zustand. Route state, game settings, and Toolkit content state are separate stores.
|
||||
|
||||
# Troubleshooting
|
||||
- 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`
|
||||
|
||||
If you're having issues getting the above steps to work, see the [Troubleshooting](https://reactnative.dev/docs/troubleshooting) page.
|
||||
Game settings currently include:
|
||||
|
||||
# Learn More
|
||||
- resolution: `browser`, `iphoneMini`, `iphoneDefault`, `androidDefault`, `phoneLarge`
|
||||
- autosave
|
||||
- audio mute
|
||||
- master, music, ambience, speech, and SFX volume
|
||||
|
||||
To learn more about React Native, take a look at the following resources:
|
||||
## Toolkit
|
||||
|
||||
- [React Native Website](https://reactnative.dev) - learn more about React Native.
|
||||
- [Getting Started](https://reactnative.dev/docs/environment-setup) - an **overview** of React Native and how setup your environment.
|
||||
- [Learn the Basics](https://reactnative.dev/docs/getting-started) - a **guided tour** of the React Native **basics**.
|
||||
- [Blog](https://reactnative.dev/blog) - read the latest official React Native **Blog** posts.
|
||||
- [`@facebook/react-native`](https://github.com/facebook/react-native) - the Open Source; GitHub **repository** for React Native.
|
||||
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 currently contains read-only planning panels for volatile gameplay systems, plus a dedicated Credits tab. Credits content is sourced from `src/data/credits.json` and synchronized through socket events for read, save, change broadcast, and refresh recovery.
|
||||
|
||||
Socket health check:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:5174/health
|
||||
```
|
||||
|
||||
## Assets
|
||||
|
||||
Image assets live in `src/assets/images/`. Fonts live in `src/assets/fonts/`. Music lives in `src/assets/music/`. Browser SCSS entrypoints live in `src/assets/scss/`.
|
||||
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user