Tom Boullay
134 lines
4.0 KiB
Markdown
134 lines
4.0 KiB
Markdown
# Zustand Game State
|
|
|
|
This document explains how Zustand is used in the current project.
|
|
|
|
## Why Zustand Exists Here
|
|
|
|
The project needs one shared source of truth for the player's progression through the experience.
|
|
|
|
The current progression is split into main states:
|
|
|
|
| Main state | Role |
|
|
| ---------- | ------------------------------- |
|
|
| `intro` | Onboarding and opening sequence |
|
|
| `bike` | E-bike repair sequence |
|
|
| `pylone` | Power grid sequence |
|
|
| `ferme` | Vertical farm sequence |
|
|
| `outro` | Ending sequence |
|
|
|
|
Each main state can also own smaller sub state, such as the current mission step, dialogue audio, or completion flags.
|
|
|
|
Zustand is useful because React and React Three Fiber components can subscribe only to the state slice they need. When that slice changes, only the subscribed components re-render.
|
|
|
|
## Store Location
|
|
|
|
The game progression store lives here:
|
|
|
|
```txt
|
|
src/managers/stores/useGameStore.ts
|
|
```
|
|
|
|
The store is placed under `src/managers/stores/` because it belongs to the gameplay orchestration layer, not to a specific visual component.
|
|
|
|
## Current Shape
|
|
|
|
The store exposes:
|
|
|
|
- `mainState`: the active game phase
|
|
- `intro`: intro-specific state
|
|
- `bike`: e-bike mission state
|
|
- `pylone`: power grid mission state
|
|
- `ferme`: farm mission state
|
|
- `outro`: ending state
|
|
- actions for direct updates and progression updates
|
|
|
|
The mission steps currently use this sequence:
|
|
|
|
```ts
|
|
"locked" | "waiting" | "inspect" | "scanning" | "repairing" | "done";
|
|
```
|
|
|
|
## Reading State In Components
|
|
|
|
Use selectors to read only what the component needs.
|
|
|
|
```tsx
|
|
import { useGameStore } from "@/managers/stores/useGameStore";
|
|
|
|
export function Example(): React.JSX.Element {
|
|
const mainState = useGameStore((state) => state.mainState);
|
|
|
|
return <p>Current state: {mainState}</p>;
|
|
}
|
|
```
|
|
|
|
This is better than reading the whole store, because the component re-renders only when `mainState` changes.
|
|
|
|
## Updating State
|
|
|
|
Prefer explicit actions from the store.
|
|
|
|
```ts
|
|
const advanceGameState = useGameStore((state) => state.advanceGameState);
|
|
|
|
advanceGameState();
|
|
```
|
|
|
|
For development and debug tooling, direct setters also exist:
|
|
|
|
```ts
|
|
const setMainState = useGameStore((state) => state.setMainState);
|
|
|
|
setMainState("bike");
|
|
```
|
|
|
|
Direct setters are useful for debug panels, but production gameplay should prefer business actions such as `advanceGameState`, `completeBike`, or `completePylone`.
|
|
|
|
## World Integration
|
|
|
|
`src/world/GameStageContent.tsx` subscribes to `mainState` and mounts stage-specific content.
|
|
|
|
That means the scene can progressively move toward this pattern:
|
|
|
|
```tsx
|
|
switch (mainState) {
|
|
case "intro":
|
|
return <IntroContent />;
|
|
case "bike":
|
|
return <BikeContent />;
|
|
case "pylone":
|
|
return <PyloneContent />;
|
|
case "ferme":
|
|
return <FarmContent />;
|
|
case "outro":
|
|
return <OutroContent />;
|
|
}
|
|
```
|
|
|
|
In React Three Fiber, mounting and unmounting JSX controls what appears in the Three.js scene. When a state-specific component disappears from JSX, React removes it from the scene.
|
|
|
|
## UI Integration
|
|
|
|
`src/components/ui/GameUI.tsx` groups the HTML overlays used by the playable route.
|
|
|
|
Current overlays:
|
|
|
|
- `GameStateHUD`: debug-only progression panel shown with `?debug`
|
|
- `Crosshair`: player aiming helper
|
|
- `InteractPrompt`: interaction prompt
|
|
|
|
`src/pages/page.tsx` should stay thin and mount only the canvas and `GameUI`.
|
|
|
|
## Regression Rules
|
|
|
|
- Do not store per-frame values in Zustand.
|
|
- Use `useRef` for high-frequency mutable values such as player velocity, temporary vectors, or animation-loop data.
|
|
- Use selectors instead of reading the whole store in components.
|
|
- Keep gameplay transitions inside store actions when possible.
|
|
- Keep debug-only controls behind `?debug`.
|
|
- Add new state only when a real runtime feature needs it.
|
|
|
|
## Next Steps
|
|
|
|
The next natural step is to replace the temporary stage anchors in `GameStageContent` with real stage components, for example `IntroContent`, `BikeContent`, `PyloneContent`, `FermeContent`, and `OutroContent`.
|