A branching-futures engine inspired by Asimov's Foundation series. It reads live geopolitical data, generates a baseline analysis of the present moment, and branches into possible futures you navigate with your hands via webcam.
The simulator has two modes. You can let it observe the present, grounding itself in current events and proposing directions based on what's actually happening. Or you can type a scenario seed ("United States invades Iran", "EU dissolves", anything) and the engine grounds that premise in reality and branches from there.
Each future forks again. You navigate this branching space with hand gestures via webcam, using an open palm to seek, pinch-and-hold to commit to a timeline, and a closed fist to collapse branches you want to discard. When you commit, the camera swoops along the causal spline into your chosen future while unchosen branches fade and prune away behind you.
A divergence dial tunes the entropy. Low keeps things close to the probable. High goes lateral and surprising. Default sits at 0.5.
| Gesture | Action |
|---|---|
| ✋ Open palm | Seek / hover over branches |
| 🤏 Pinch & hold | Commit to a timeline |
| ✊ Closed fist | Collapse a branch |
| ✌️ Peace sign | Adjust divergence dial |
| 🤙 Thumb-to-pinky | Rewind through committed history |
You can also click nodes directly and use Backspace/Escape to go back.
- Node.js (v18+)
- A Gemini API key
git clone https://github.com/justinwetch/psychohistory.git
cd psychohistory
npm installAdd your API key. Either create a .env file:
VITE_GEMINI_API_KEY=your_key_here
Or paste it into the modal when the app starts.
Then:
npm run devOpen http://localhost:5173 in a browser with webcam access.
The app will request webcam access for hand tracking. Gesture control is optional. Mouse and keyboard work as fallback inputs.
| Layer | Technology |
|---|---|
| Rendering | Three.js |
| Animation | GSAP |
| Hand tracking | MediaPipe |
| AI | Gemini API (REST, no SDK) |
| Build | Vite |
No framework. Vanilla JS.
The 3D scene is managed by a single PsychohistoryScene class in main.js. Key patterns:
- Shell node pattern: 3D geometry spawns instantly during camera animations. Content fills in asynchronously from the API so there's never a loading screen.
- Realpolitik prompts: The generation in
prompts.jsis grounded in actor-incentive analysis. States acting in rational self-interest, domestic politics constraining foreign policy, least-costly moves. Without this structural grounding, outputs spiral into either apocalypse or utopia within two turns. - Lightcone projection: Futures project into the Z-axis as a lightcone into 3D space, not a flat tree. Further branches scale down and desaturate for natural depth-of-field fade.
- Causal minimap: An SVG minimap renders the full branching topology from above.
psychohistory/
index.html # UI layer: modal, dashboard, gesture legend, minimap
main.js # 3D scene, camera, gestures, node/branch logic
api.js # Gemini REST wrapper, caching, baseline/branch generation
prompts.js # Prompt templates for realpolitik scenario modeling
index.css # Gold-on-obsidian aesthetic, spatial card styles
package.json
MIT