# thepie88/fo4_wrld architecture

> Architecture diagram of the GitHub repository thepie88/fo4_wrld, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thepie88/fo4_wrld
- Repository: https://github.com/thepie88/fo4_wrld

## Overview

FO4_Wrld is a Fallout 4 multiplayer mod targeting persistent-world play. A player launches a configured game client, which reports local state and gameplay events to the UDP server; the server validates and relays shared state, and each client applies remote-player and world updates through its native DLL and renders them in-game. The README documents position, pose, appearance/equipment, world-object, session, chat, and discovery capabilities. Several detailed subsystem links rely on README documentation because their source was not sampled.

Main entry points: [`net/server/main.py`](https://github.com/thepie88/fo4_wrld/blob/master/net/server/main.py) (Game server), [`net/client/main.py`](https://github.com/thepie88/fo4_wrld/blob/master/net/client/main.py) (Python client), [`fw_native/src/net/client.cpp`](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/net/client.cpp) (Native network client), [`fw_native/src/engine/engine_calls.cpp`](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/engine/engine_calls.cpp) (Engine calls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch and setup"]
  node_launcher["Python launcher<br/>[main.py]"]
  node_orchestrator["Game orchestrator<br/>[orchestrator.py]"]
end

subgraph group_client["Game client"]
  node_native["Native DLL<br/>[dll_main.cpp]"]
  node_ghost["Ghost actors<br/>[actor_hijack.cpp]"]
  node_hooks["Game hooks<br/>[install_all.cpp]"]
  node_engine["Engine calls<br/>[engine_calls.cpp]"]
  node_appearance["Appearance and pose"]
  node_worldhooks["World event hooks"]
end

subgraph group_wire["Networking"]
  node_clientnet["Native network client<br/>[client.cpp]"]
  node_pyclient["Python client<br/>[main.py]"]
  node_fridabridge["Frida bridge<br/>[frida_bridge.py]"]
  node_protocol["Wire protocol<br/>[protocol.py]"]
end

subgraph group_server["Authoritative services"]
  node_server["Game server<br/>[main.py]"]
  node_validator["State validator<br/>[validator.py]"]
  node_state[("World state<br/>[state.py]")]
  node_persistence["Snapshot persistence<br/>[persistence.py]"]
  node_ownership["NPC ownership<br/>[ownership.py]"]
  node_master["Master directory<br/>[main.py]"]
end

subgraph group_presentation["In-game presentation"]
  node_overlay["In-game overlay<br/>[overlay.cpp]"]
  node_chat["Chat and names<br/>[chat_overlay.cpp]"]
end

node_player(("Player"))
node_fo4["Fallout 4"]

node_player -->|"starts client"| node_launcher
node_launcher -->|"configures launch"| node_orchestrator
node_orchestrator -->|"starts game"| node_fo4
node_fo4 -->|"loads proxy DLL"| node_native
node_native -->|"installs detours"| node_hooks
node_hooks -->|"invokes engine"| node_engine
node_pyclient -->|"reads player state"| node_fridabridge
node_fridabridge -->|"returns readings"| node_pyclient
node_pyclient -->|"sends client state"| node_server
node_server -->|"validates events"| node_validator
node_server -->|"updates authoritative state"| node_state
node_server -->|"relays broadcasts"| node_pyclient
node_server -->|"loads and saves snapshots"| node_persistence
node_server -->|"elects NPC owner"| node_ownership
node_server -.->|"registers listing"| node_master
node_pyclient -.->|"requests server list"| node_master
node_clientnet -->|"dispatches remote updates"| node_ghost
node_clientnet -->|"stores remote pose"| node_appearance
node_clientnet -->|"dispatches world updates"| node_worldhooks
node_worldhooks -->|"applies world changes"| node_engine
node_ghost -->|"builds and positions actors"| node_engine
node_clientnet -->|"delivers chat"| node_chat
node_player -->|"uses in-game UI"| node_overlay
node_overlay -->|"shows chat"| node_chat

click node_launcher "https://github.com/thepie88/fo4_wrld/blob/master/launcher/main.py"
click node_orchestrator "https://github.com/thepie88/fo4_wrld/blob/master/launcher/orchestrator.py"
click node_native "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/dll_main.cpp"
click node_clientnet "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/net/client.cpp"
click node_pyclient "https://github.com/thepie88/fo4_wrld/blob/master/net/client/main.py"
click node_fridabridge "https://github.com/thepie88/fo4_wrld/blob/master/net/client/frida_bridge.py"
click node_protocol "https://github.com/thepie88/fo4_wrld/blob/master/net/protocol.py"
click node_server "https://github.com/thepie88/fo4_wrld/blob/master/net/server/main.py"
click node_validator "https://github.com/thepie88/fo4_wrld/blob/master/net/server/validator.py"
click node_state "https://github.com/thepie88/fo4_wrld/blob/master/net/server/state.py"
click node_persistence "https://github.com/thepie88/fo4_wrld/blob/master/net/server/persistence.py"
click node_ownership "https://github.com/thepie88/fo4_wrld/blob/master/net/server/ownership.py"
click node_master "https://github.com/thepie88/fo4_wrld/blob/master/net/master/main.py"
click node_ghost "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/ghost/actor_hijack.cpp"
click node_hooks "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/hooks/install_all.cpp"
click node_engine "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/engine/engine_calls.cpp"
click node_appearance "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/native/appearance_recipe.cpp"
click node_worldhooks "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/hooks/worldstate_hook.cpp"
click node_overlay "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/render/overlay.cpp"
click node_chat "https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/render/chat_overlay.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_orchestrator toneBlue
class node_native,node_ghost,node_hooks,node_engine,node_appearance,node_worldhooks toneAmber
class node_clientnet,node_pyclient,node_fridabridge,node_protocol toneMint
class node_server,node_validator,node_state,node_persistence,node_ownership,node_master toneRose
class node_overlay,node_chat,node_player,node_fo4 toneIndigo
```

## Components

### Launch and setup

- [Python launcher](https://github.com/thepie88/fo4_wrld/blob/master/launcher/main.py): `launcher/main.py`
- [Game orchestrator](https://github.com/thepie88/fo4_wrld/blob/master/launcher/orchestrator.py): `launcher/orchestrator.py`

### Game client

- [Native DLL](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/dll_main.cpp): `fw_native/src/dll_main.cpp`
- [Ghost actors](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/ghost/actor_hijack.cpp): `fw_native/src/ghost/actor_hijack.cpp`
- [Game hooks](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/hooks/install_all.cpp): `fw_native/src/hooks/install_all.cpp`
- [Engine calls](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/engine/engine_calls.cpp): `fw_native/src/engine/engine_calls.cpp`
- [Appearance and pose](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/native/appearance_recipe.cpp): `fw_native/src/native/appearance_recipe.cpp`
- [World event hooks](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/hooks/worldstate_hook.cpp): `fw_native/src/hooks/worldstate_hook.cpp`

### Networking

- [Native network client](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/net/client.cpp): `fw_native/src/net/client.cpp`
- [Python client](https://github.com/thepie88/fo4_wrld/blob/master/net/client/main.py): `net/client/main.py`
- [Frida bridge](https://github.com/thepie88/fo4_wrld/blob/master/net/client/frida_bridge.py): `net/client/frida_bridge.py`
- [Wire protocol](https://github.com/thepie88/fo4_wrld/blob/master/net/protocol.py): `net/protocol.py`

### Authoritative services

- [Game server](https://github.com/thepie88/fo4_wrld/blob/master/net/server/main.py): `net/server/main.py`
- [State validator](https://github.com/thepie88/fo4_wrld/blob/master/net/server/validator.py): `net/server/validator.py`
- [World state](https://github.com/thepie88/fo4_wrld/blob/master/net/server/state.py): `net/server/state.py`
- [Snapshot persistence](https://github.com/thepie88/fo4_wrld/blob/master/net/server/persistence.py): `net/server/persistence.py`
- [NPC ownership](https://github.com/thepie88/fo4_wrld/blob/master/net/server/ownership.py): `net/server/ownership.py`
- [Master directory](https://github.com/thepie88/fo4_wrld/blob/master/net/master/main.py): `net/master/main.py`

### In-game presentation

- [In-game overlay](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/render/overlay.cpp): `fw_native/src/render/overlay.cpp`
- [Chat and names](https://github.com/thepie88/fo4_wrld/blob/master/fw_native/src/render/chat_overlay.cpp): `fw_native/src/render/chat_overlay.cpp`

### Other components

- **Player**
- **Fallout 4**

## Connections

- Player → Python launcher: starts client
- Python launcher → Game orchestrator: configures launch
- Game orchestrator → Fallout 4: starts game
- Fallout 4 → Native DLL: loads proxy DLL
- Native DLL → Game hooks: installs detours
- Game hooks → Engine calls: invokes engine
- Python client → Frida bridge: reads player state
- Frida bridge → Python client: returns readings
- Python client → Game server: sends client state
- Game server → State validator: validates events
- Game server → World state: updates authoritative state
- Game server → Python client: relays broadcasts
- Game server → Snapshot persistence: loads and saves snapshots
- Game server → NPC ownership: elects NPC owner
- Game server → Master directory: registers listing
- Python client → Master directory: requests server list
- Native network client → Ghost actors: dispatches remote updates
- Native network client → Appearance and pose: stores remote pose
- Native network client → World event hooks: dispatches world updates
- World event hooks → Engine calls: applies world changes
- Ghost actors → Engine calls: builds and positions actors
- Native network client → Chat and names: delivers chat
- Player → In-game overlay: uses in-game UI
- In-game overlay → Chat and names: shows chat