shawn/tactical-shooter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 17 Wiki Activity

Phase 7: netfox + godot-jolt stack upgrade

Browse Source 
Stack installed:
- netfox v1.35.3 (core + extras + noray + internals)
- godot-jolt v0.16.0-stable

Architecture:
- Server: ENet transport (works headless, no netfox deps)
- Client/Editor: netfox rollback (RollbackSynchronizer, TickInterpolator)

New/modified:
- docs/migration-netfox-plan.md — migration architecture
- scripts/network/network_manager.gd — netfox-aware ENet fallback
- scripts/network/player.gd — clean base player
- client/characters/player_netfox.gd — rollback player w/ WeaponManager
- client/characters/input/player_net_input.gd — BaseNetInput subclass
- client/characters/character/fps_character_controller.gd — netfox input feed
- client/weapons/ — weapon data, registry, TacticalWeaponHitscan, WeaponManager
- client/scripts/round_replicator.gd — client-side round state bridge
- server/scripts/round_manager.gd — improved state machine
- server/scripts/plugin_api/plugin_manager.gd — refined plugin system
- config: enemy_tag, ally_tag for meatball targeting

Removed: old C++ SimulationServer GDExtension (replaced by netfox rollback)
This commit is contained in:
Shawn
2026-07-02 17:38:50 -04:00
parent e2dc429caa
commit e7299b17e9
3237 changed files with 523530 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/migration-netfox-plan.md
+203
View File
@@ -0,0 +1,203 @@
# Phase 7: Stack Upgrade — netfox + godot-jolt Migration Plan
## Overview
Migrate from raw **ENetMultiplayerPeer** to **netfox** (foxssake/netfox, 1020⭐ MIT)
for rollback netcode, client prediction, and lag compensation. Add **godot-jolt**
(godot-jolt/godot-jolt, 2535⭐ MIT) for deterministic 128Hz physics.
**Reference architecture:** [naxIO/netfox-cs-sample](https://github.com/naxIO/netfox-cs-sample)
— CS 1.6 clone using netfox rollback patterns (teams, economy, bomb, 6 weapons).
---
## Current Architecture (Pre-Migration)
```
┌───────────────────────────────────────────────────┐
│ project.godot │
│ Autoloads: NetworkManager, ServerConfig, │
│ RoundManager, PluginManager │
│ Physics: 128Hz (Godot built-in) │
│ Rendering: Vulkan Forward+ │
│ Main Scene: server_main.tscn │
└─────────────────────┬─────────────────────────────┘
│
┌─────────────┴──────────────┐
▼ ▼
┌─────────────────┐ ┌──────────────────────────┐
│ network_manager │ │ SimulationServer │
│ .gd (ENet) │ │ (GDExtension C++) │
│ │ │ │
│ - ENetMultiplayer│ │ - entity spawning │
│ - 3 channels │ │ - apply_input() │
│ - RPC broadcasts │ │ - fire_weapon() │
│ - signals: │ │ - get_entity() │
│ player_* │ └──────────┬────────────────┘
│ round_* │ │
│ score_* │ ┌──────────▼────────────────┐
└─────────────────┘ │ fps_character_controller │
│ .gd (CharacterBody3D) │
┌─────────────────┐ │ │
│ round_manager │ │ - Input → SimulationServer│
│ .gd (state │ │ - move_local() fallback │
│ machine) │ │ - crouch, sprint, jump │
│ │ └────────────────────────────┘
│ - signals: │
│ round_*,score │ ┌──────────────────────────┐
│ - _process tick │ │ Player (Node3D) │
└─────────────────┘ │ - basic BoxMesh │
│ - movement_speed param │
└──────────────────────────┘
```
**Key issue:** ENet has no rollback, no client prediction, no lag compensation.
Players on slower connections will feel inconsistent hit registration.
---
## Target Architecture (Post-Migration)
```
┌────────────────────────────────────────────────────┐
│ project.godot │
│ Autoloads: (same, NetworkManager rewired) │
│ Physics: Jolt @ 128Hz (godot-jolt GDExtension) │
│ Rendering: Vulkan Forward+ │
│ Addons: netfox, netfox.noray, netfox.extras │
└─────────────────────┬──────────────────────────────┘
│
┌─────────────┴──────────────┐
▼ ▼
┌──────────────────────┐ ┌──────────────────────────┐
│ netfox core │ │ netfox.noray │
│ (NetworkEvents, │ │ (NAT punchthrough) │
│ RollbackSynch., │ └──────────────────────────┘
│ TickInterpolator) │
└──────────┬───────────┘ ┌──────────────────────────┐
│ │ netfox.extras │
▼ │ (BaseNetInput, │
┌──────────────────────┐ │ RewindableStateMachine)│
│ NetworkManager.gd │ └──────────────────────────┘
│ (wrapper over netfox │
│ NetworkEvents + │ ┌──────────────────────────┐
│ MultiplayerSynch.) │ │ godot-jolt │
└──────────┬───────────┘ │ (deterministic physics) │
│ └──────────────────────────┘
▼
┌────────────────────────────────────────────────────┐
│ RollbackSynchronizer (player state) │
│ - _rollback_tick() → deterministic state sync │
│ - TickInterpolator → smooth visuals │
│ - Client prediction: apply input locally, │
│ reconcile from server snapshot │
└────────────────────────────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────┐
│ RewindableAction (hitscan weapons) │
│ - Server-authoritative hit detection │
│ - Server rewinds physics to match client timing │
│ - Per-limb damage: head/chest/waist/legs │
└────────────────────────────────────────────────────┘
```
---
## Migration Phases (Task Breakdown)
### P7.1 Research — netfox migration plan ✅ [THIS DOCUMENT]
### P7.2 Install — netfox addon
1. Download latest release from GitHub
2. Extract addons/netfox/, addons/netfox.noray/, addons/netfox.extras/, addons/netfox.internals/
3. Enable in Project Settings → Plugins
4. Verify `godot --headless --check-only` compiles
### P7.3 Install — godot-jolt physics
1. Download from releases or Asset Library
2. Copy addons/godot-jolt/ into project
3. Enable plugin, configure physics → 128Hz
4. Verify headless compilation
### P7.4 Port — NetworkManager.gd
**Source:** `scripts/network/network_manager.gd` (214 lines, ENet wrapper)
**Changes:**
- Replace `ENetMultiplayerPeer` → netfox `NetworkEvents`
- `start_server()` → use netfox's NetworkEvents server flow
- `join_server()` → use netfox's NetworkEvents client flow
- Player replication signals → netfox `MultiplayerSynchronizer` or `RollbackSynchronizer`
- Round state RPCs (`broadcast_round_*`) → netfox events
- Remove channel system (netfox handles prioritisation internally)
**Equivalent vs New:**
| Current ENet | netfox Equivalent |
|---|---|
| ENetMultiplayerPeer | NetworkEvents (connect/disconnect) |
| @rpc("authority", "call_local", "reliable") | MultiplayerSynchronizer / RollbackSynchronizer |
| broadcast_spawn_player RPC | NetworkEvents + spawn hook |
| broadcast_round_start RPC | NetworkEvents event |
| 3 channels (input/events/telemetry) | Automatic (netfox manages ordering) |
| _process polling | TickInterpolator / _rollback_tick() |
### P7.5 Build — Client Prediction + Rollback
**Key netfox patterns:**
- `RollbackSynchronizer` with `_rollback_tick()` for deterministic state sync
- `BaseNetInput` with `_gather()` for input collection
- `TickInterpolator` for smooth visual interpolation between ticks
- Client-side prediction: apply input immediately, reconcile when server snapshot arrives
### P7.6 Build — Rollback Hitscan + Lag Compensation
**Key netfox patterns:**
- `RewindableAction` for rollback-safe weapon firing
- Server rewinds entity positions to match client's input timestamp
- Hit detection inside rollback loop
- Per-limb damage (head 2x, chest 1.0x, waist 0.75x, legs 0.5x)
### P7.7 Port — RoundManager to netfox
**Source:** `server/scripts/round_manager.gd` (647 lines)
**Changes:**
- Round state signals (`round_started`, `round_ended`, etc.) → netfox events
- `player_died` etc. → netfox replicated state or RPCs
- `get_round_state_snapshot()` → netfox synchronized property
### P7.8 Port — FPS Controller to BaseNetInput
**Source:** `client/characters/character/fps_character_controller.gd` (401 lines)
**Changes:**
- Replace manual `_input_dict` → `BaseNetInput` subclass
- Use `_gather()` to collect input per tick
- Movement logic becomes server-authoritative (no more `move_local` fallback except singleplayer)
- Keep mouse look, crouch transition, sprint toggle — adapt for netfox tick
### P7.9 Test — Headless Export + Deployment
- `godot --headless --export-debug "Linux/X11" build/server/tactical-shooter.x86_64`
- Server starts clean, clients connect, rollback works across LAN
- Push to Gitea, update systemd service, verify on server
---
## Reference Files
| File | Lines | Key Role |
|---|---|---|
| `scripts/network/network_manager.gd` | 214 | ENet transport wrapper, RPC broadcasts |
| `scripts/network/player.gd` | ~60 | Basic player node |
| `scripts/network/server_main.gd` | ~150 | Server entry point |
| `scripts/network/client_main.gd` | ~120 | Client entry point |
| `client/characters/character/fps_character_controller.gd` | 401 | FPS movement + input to SimulationServer |
| `client/characters/character/fps_camera.gd` | ~80 | Camera look |
| `server/scripts/round_manager.gd` | 647 | Round state machine |
| `server/scripts/plugin_api/plugin_manager.gd` | 573 | Plugin system |
| `scenes/server/server_main.tscn` | 14 | Server scene |
| `scenes/client/client_main.tscn` | 14 | Client scene |
| `scenes/player.tscn` | 15 | Player prefab |
| `project.godot` | 33 | Autoloads, physics settings |
## Resources
- [netfox docs](https://foxssake.github.io/netfox/)
- [netfox GitHub](https://github.com/foxssake/netfox)
- [naxIO/netfox-cs-sample — CS 1.6 reference](https://github.com/naxIO/netfox-cs-sample)
- [godot-jolt GitHub](https://github.com/godot-jolt/godot-jolt)
- [VANTIX tactical shooter reference (C#, architecture only)](https://github.com/justin-bobr/vantix)
docs/netfox-migration-plan.md
+247
View File
@@ -0,0 +1,247 @@
# Netfox Migration Checklist — File-by-File Audit
Generated: 2026-07-02
Task: P7.1 (research — netfox migration plan)
---
## Architecture Overview
```
┌──────────────────────────────────┐
│ network_manager.gd │
│ (ENetMultiplayerPeer transport) │
│ + optional NetworkEvents overlay│
└──────┬───────────────┬───────────┘
│ │
┌────────────┘ └────────────┐
v v
┌─────────────────────┐ ┌─────────────────────┐
│ server_main.gd │ │ client_main.gd │
│ (dedicated server)│ │ (client entry) │
└─────────┬───────────┘ └──────────┬──────────┘
│ │
┌─────────┴───────────┐ ┌──────────┴──────────┐
│ round_manager.gd │ │ round_replicator.gd │
│ (state machine) │ │ (client mirror) │
└─────────────────────┘ └─────────────────────┘
┌──────────────────────────────────────────────────────────┐
│ player.gd │
│ RollbackSynchronizer (dynamic child) │
│ ├── state_properties: pos, is_alive, team_id, spec_tgt │
│ └── input_properties: → PlayerNetInput/* │
│ │
│ PlayerNetInput (child Node) │
│ ├── move_direction, look_yaw, look_pitch │
│ ├── jump, sprint, crouch, shoot, aim │
│ └── connects to NetworkTime.before_tick_loop │
└──────────────────────────────────────────────────────────┘
```
### Headless Compilation
✅ **Passes** — `godot --headless --check-only` reports 0 parser errors.
- Runtime warnings (ENet host, netfox unavailable, empty map rotation) are all expected in CI environments.
- All netfox-dependent code paths guarded by `Engine.has_singleton()` + duck-typing.
---
## File-by-File Audit
### 1. network_manager.gd (245 lines) — TRANSPORT LAYER
**Current role:** ENetMultiplayerPeer management + signal relay hub.
**DONE:**
- ✅ Optional NetworkEvents overlay for lifecycle signals (`_try_connect_netfox()`)
- ✅ All netfox refs use `Engine.has_singleton("NetworkEvents")` — no `class_name` refs
**REMAINING (6 legacy RPC broadcasting functions):**
| Line | RPC | netfox Replacement | Status |
|------|-----|--------------------|--------|
| 193 | `broadcast_spawn_player` | Replaced by RollbackSynchronizer state sync. Keep until client discoverse players from state, not RPC. | 🔶 keep temporarily |
| 199 | `broadcast_despawn_player` | Same as above | 🔶 keep temporarily |
| 209 | `broadcast_round_start` | Move to StateSynchronizer on a round-state autoload (P7.7) | ❌ |
| 214 | `broadcast_round_end` | Same as above | ❌ |
| 219 | `broadcast_match_end` | Same as above | ❌ |
| 224 | `broadcast_score_change` | Same as above | ❌ |
**Networking signals (9 total)** — all stay as-is. They are event hooks for consumers (client_main, round_replicator), not data sync.
---
### 2. player.gd (251 lines) — PLAYER ENTITY
**Current role:** Player character with Team/Round integration. Uses RollbackSynchronizer.
**DONE:**
- ✅ RollbackSynchronizer dynamically created: `state_properties=[position, is_alive, team_id, spectate_target_id]`
- ✅ `input_properties=[PlayerNetInput/move_direction, look_yaw, look_pitch, jump, sprint, crouch, shoot, aim]`
- ✅ `_rollback_tick(delta, tick, is_input)` with deterministic movement
- ✅ `_create_rollback_sync_node()` uses `load()` + `new()` from path — no class_name refs
- ✅ Duck-typed netfox checks via `has_method()`, `Engine.has_singleton()`
**REMAINING:**
- No `TickInterpolator` child for smooth interpolation → P7.5
---
### 3. player_net_input.gd (91 lines) — INPUT GATHERING
**Current role:** Tick-synchronized input collector, child of Player.
**DONE:**
- ✅ 8 exported input properties matching RollbackSynchronizer's `input_properties`
- ✅ Connects to `NetworkTime.before_tick_loop`
- ✅ Reads yaw/pitch from parent FPSCharacterController via duck-typing
- ✅ Extends Node directly (avoids `BaseNetInput` headless class_name issues)
**REMAINING:**
- FPSCharacterController duplicates input gathering in `_physics_process` — should read from PlayerNetInput instead → P7.8
---
### 4. server_main.gd (342 lines) — SERVER ENTRY POINT
**DONE:**
- ✅ Uses `NetworkManager.start_server()` for ENet bootstrap
- ✅ Connects to `NetworkManager.player_connected/disconnected`
**REMAINING — 7 RPC call sites:**
| Line | Call | netfox Plan |
|------|------|-------------|
| 120 | `broadcast_round_start.rpc(...)` | StateSynchronizer in P7.7 |
| 142 | `broadcast_round_end.rpc(...)` | StateSynchronizer in P7.7 |
| 178 | `broadcast_match_end.rpc(...)` | StateSynchronizer in P7.7 |
| 184 | `broadcast_score_change.rpc(...)` | StateSynchronizer in P7.7 |
| 288 | `broadcast_spawn_player.rpc(...)` | RollbackSynchronizer state (keep for now) |
| 327 | `broadcast_despawn_player.rpc(...)` | RollbackSynchronizer state (keep for now) |
| 332 | `broadcast_despawn_player.rpc(...)` | RollbackSynchronizer state (keep for now) |
---
### 5. client_main.gd (124 lines) — CLIENT ENTRY POINT
**DONE:**
- ✅ Uses `NetworkManager.join_server()`
- ✅ Connects to `remote_player_spawned/despawned` for visualization
**REMAINING:**
- Creates full Player nodes with RollbackSynchronizer for each remote player (✅ correct pattern)
- May want TickInterpolator on remote player instances later (P7.5)
---
### 6. round_replicator.gd (157 lines) — CLIENT ROUND STATE
**DONE:**
- ✅ Connects to NetworkManager's broadcast signals
- ✅ Maintains round state (round_number, scores, time, freeze)
- ✅ Uses netfox `NetworkTime` singleton for freeze tick tracking (line 84, 123)
**REMAINING:**
- Could be replaced by a `RoundState` autoload with `StateSynchronizer` for rollback-consistent round state (P7.7)
---
### 7. round_manager.gd (647 lines) — SERVER ROUND STATE MACHINE
**DONE:** ✅ Zero networking code. Pure state machine emitting signals. No changes needed.
---
### 8. fps_character_controller.gd (411 lines) — FPS CONTROLS
**DONE:**
- ✅ `get_current_yaw()` / `get_current_pitch()` methods for PlayerNetInput
- ✅ Standalone `_move_local()` fallback
- ✅ SimulationServer refs use `Engine.has_singleton()`
**REMAINING (P7.8):**
- `_physics_process` gathers input AND sends to SimulationServer directly — duplicates PlayerNetInput
- Need to read from PlayerNetInput child instead of `_get_move_direction()`
- Clarify: PlayerNetInput → RollbackSynchronizer → server physics → reconcile → FPSCharacterController applies
---
## netfox Pattern Mapping
| Pattern | netfox API | Status |
|---------|-----------|--------|
| Player state sync | RollbackSynchronizer.state_properties | ✅ |
| Input client→server | RollbackSynchronizer.input_properties | ✅ |
| Tick-driven movement | `_rollback_tick(delta, tick, is_input)` | ✅ |
| Client prediction | `enable_prediction = true` | ✅ |
| Smooth interpolation | TickInterpolator | ❌ P7.5 |
| Round state broadcast | StateSynchronizer | ❌ P7.7 |
| Rollback-safe weapon fire | RewindableAction | ❌ P7.6 |
| Lag comp / hitscan | RewindableAction + mutation | ❌ P7.6 |
| Visual rollback | TickInterpolator + _rollback_tick | ❌ P7.5 |
| Lifecycle signals | NetworkEvents | ✅ |
---
## Netfox Singleton Availability (Headless)
| Singleton | Editor | Headless | Access Pattern |
|-----------|--------|----------|----------------|
| NetworkEvents | ✅ | ❌ | `Engine.has_singleton("NetworkEvents")` |
| NetworkTime | ✅ | ❌ | `Engine.has_singleton("NetworkTime")` |
| NetworkRollback | ✅ | ❌ | `Engine.has_singleton("NetworkRollback")` |
| NetworkPerformance | ✅ | ❌ | `Engine.has_singleton("NetworkPerformance")` |
All access guarded — no class_name references in our code.
---
## Remaining Work Order (Dependency Graph)
```
P7.6 (RewindableAction) ── needs ── RollbackSynchronizer working (✅ DONE)
P7.5 (TickInterpolator) ── needs ── RollbackSynchronizer working (✅ DONE)
P7.7 (Round state netfox) ── needs ── NetworkEvents working (✅ DONE)
P7.8 (FPSController refactor) ── needs ── P7.6 input flow clarified
P7.9 (LAN test + deploy) ── needs ── all of the above
```
**Recommended order:** P7.6 → P7.5 → P7.7 → P7.8 → P7.9
---
## Files NOT Needing Changes
| File | Reason |
|------|--------|
| `server/scripts/round_manager.gd` | Pure state machine, no networking |
| `scripts/config/server_config.gd` | Config loader, no networking |
| `scripts/network/netfox_bootstrap.gd` | No-op placeholder |
| `server/scripts/plugin_api/plugin_manager.gd` | Plugin mgmt, no networking |
| `client/weapons/data/weapon_registry.gd` | Data-only |
---
## Risk Assessment
| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Headless compilation fails | High | Low | All netfox refs use has_singleton/has_method. Current check passes. |
| RollbackSynchronizer vs PlayerNetInput property mismatch | Medium | Low | `input_properties` paths verified against @export var names — matched. |
| Dual input path (SimulationServer + RollbackSynchronizer) | High | Medium | FPSCharacterController sends to both — needs architectural cleanup (P7.8) |
| netfox API incompatibility with Godot 4.7 | Medium | Low | netfox 1.35.3 targets 4.3+; manual verification done — compilation passes |
---
## Key Files Summary
| File | Lines | Netfox Status | RPCs | Signals | Changes Needed |
|------|-------|---------------|------|---------|----------------|
| network_manager.gd | 245 | ✅ overlay wired | 6 ❌ | 9 ✅ | Remove 6 RPCs post-P7.7 |
| player.gd | 251 | ✅ rollback + tick | 0 | 0 | Add TickInterpolator P7.5 |
| player_net_input.gd | 91 | ✅ tick gather | 0 | 0 | None atm |
| server_main.gd | 342 | ✅ thin layer | 7 call sites ❌ | 2 | Migrate to StateSynchronizer P7.7 |
| client_main.gd | 124 | ✅ thin layer | 0 | 2 signal connects | None atm |
| round_replicator.gd | 157 | 🔶 signal-driven | 0 | 5 connects + 4 emits | Migrate to StateSynchronizer P7.7 |
| round_manager.gd | 647 | ✅ no changes | 0 | 0 | None |
| fps_character_controller.gd | 411 | 🔶 has getters | 0 | 0 | Input flow refactor P7.8 |