Introduce a server-authoritative world-state packet to control weather and time from the dev server GUI. Adds protocol docs and message type (serverWorldState), a new Weather/Time tab in dev_server_app.py, server-side broadcasting in server_core.py, and preset utilities in server/world_state_presets.py. Plugin changes (F4TNetworking.cpp, F4TWorldStateSync.*) queue and apply incoming serverWorldState on the game thread, run `set gamehour` for all clients, and run `fw <8-digit-id>` on the assigned player 1 then force the host to relay a worldState snapshot. Also includes parsing/validation of hex form IDs, logging improvements, and minimal fake client handling. This ensures consistent server-driven time/weather and documents usage and presets.
Introduce an optional timeSync field and event-driven time pushes so host time is only re-applied on connect, resume-from-freeze, or large jumps while weather continues on ~1 Hz heartbeats. Added IsGameTimeFrozen detection and client buffering of latest host time; clients apply host time only when timeSync is true or when gameplay just resumed. Updated networking to read/write timeSync, adjusted F4TWorldStateSync logic (separate time vs weather send/apply paths, changed function signatures and behavior), and updated protocol/docs/changelog and fake_client logging to reflect the new field and behavior.
Implement host-authoritative time/weather sync across server and clients. Adds a new worldState packet (and worldStateHost for host assignment) and server-side host tracking/reassignment to the lowest remaining playerId when the host disconnects. Plugin-side changes introduce F4T::WorldStateSync (new header + implementation), polling/apply hooks in the game-thread main loop, and Networking support to send/receive/parse worldState/worldStateHost packets. The server validates host-only sends, relays worldState to peers, broadcasts worldStateHost on host handoff, and augments logging/stats. Protocol and documentation files updated (protocol/world-state.md, docs/*) and server/fake_client.py extended to track/print host world-state snapshots.
Add stage-mod.bat and update build scripts to stage the mod package instead of automatically deploying (build-all.bat now calls stage-mod.bat; build.bat prints plugin output path and packaging hint). Reorganize Creation Kit assets into DataFolder and RawAssets directories, add new mesh/texture files, and update CommonwealthOnline_Vault109.esp. Also include ancillary updates to deploy scripts, docs, and server code to reflect the new packaging workflow.
Add new Papyrus scripts (CoSync.psc, CoSyncPlayer.psc, CoSyncQuest.psc) providing native bindings and quest/player proxy logic for networking: connection/session APIs, entity management, world/weather/workshop/companion sync, consumable/pipboy/door/power-armor events, and proxy animation/initialization handlers. Refactor the proxy actor controller (F4TProxyActorController.cpp) to support dynamic/runtime proxy spawning and improved lifecycle/visibility handling: change proxy base/form IDs to COPlayerProxy/CommonwealthOnline, add process-list actor lookup, spawn helpers, play-space/cell checks, 3D visibility refresh, ActorHandle usage, and spawn mutexes and globals for safer spawning. Update docs and setup (architecture.md, limitations.md, plugin/setup.md) to describe global dynamic spawn behavior, max runtime proxies (kMaxRuntimeProxyActors = 4), and validation checklist; update launch-two-fallout4.bat to show instance log locations. Misc: small tweaks to logging and debug flags to gate diagnostics.
Investigation summary:
- Tested velocity-based animation triggering: graph variable writes, animation
events, character controller velocity manipulation, and Move() API calls
- All approaches failed: animations do not play on SetPosition-backed proxy actors
- Root cause: Fallout 4's animation system requires active AIProcess-driven
locomotion packages, which are incompatible with networked puppet actors
- Fallout 4's animation system fundamentally ties animation evaluation to the
character controller's actual velocity AND active AI-driven locomotion state
- PlaceAtMe proxies updated via SetPosition cannot provide either requirement
Proxy actors currently work correctly for:
- Smooth position synchronization
- Heading/rotation updates
- Jump animations (via Z-position)
- Network sync and lifecycle
What remains impossible without deep engine access:
- Walk/run/sneak animation playback
- Animation graph variable manipulation affecting behavior
- Character controller velocity synthesis for puppets
Recommendation: Accept this architectural limitation and provide alternative
visual feedback (particles, glows, state indicators) instead of animations.
Files changed:
- plugin/src/F4TProxyActorController.cpp: Reverted to SetPosition-only approach
- docs/dev-log.md: Added comprehensive investigation summary and conclusions
Co-authored-by: Cursor <cursoragent@cursor.com>
Track and log per-slot animation/movement diagnostics for runtime proxy actors without applying any visual animation. Adds a ProxyAnimationSpeedBucket enum and GetProxyAnimationSpeedBucket/GetProxyAnimationSpeedBucketLabel helpers, a new UpdateProxyAnimationStateDebug() routine, and fields on ProxyActorSlot to remember last-observed moving, sprinting, sneaking, jumping, weapon-drawn, movement type, and coarse speed-bucket state. Resets observation state when slots are created/reused and emits initial/transition-only logs including playerId and proxy FormID. Documentation and dev-log entries updated; visual animation, animation graph changes, and AI/movement behavior remain intentionally unmodified.
Add a safe neutralization pass for Stage 4 runtime proxy actors and document the change. Introduces NeutralizeProxyActor and supporting helpers (ProxyNeutralizationReason, GetProxyNeutralizationReasonLabel, FormatPosition, IsProxyMovementPackageType, IsProxyFleeOrAlarmPackageType) plus kProxyNeutralizationInterval and a compile-time gate kEnableProxyAIMovementIntentSuppression (default=false). Adds SuppressProxyAIMovementIntent (default-disabled due to a crash observed during testing) which attempts safe package/process interruption using only confirmed CommonLibF4 APIs (EndInterruptPackage, InitiateDoNothingPackage, SetAvoidanceDisabled, command/process handle clears) and extensive throttled logs and TODOs for further unsafe changes. Neutralization is invoked after spawn promotion, on slot reassignment, during active maintenance, and while holding. Updates plugin logic to call neutralization at these points. Updates docs/architecture.md and docs/dev-log.md with the design, testing notes, and rationale (including the safety gate and next steps). Builds succeed; manual in-game validations are still pending.
Refine Stage 4 runtime proxy management: introduce explicit lifecycle states (HeldNoRemote, HeldDisconnected, HeldLeftCell, Reusable, SpawnFailed), add a 30s disconnected-slot reuse delay, and implement per-slot hidden holding positions with spacing. Add a held-position correction pass (correct drift >25 units) and make disconnected-held slots become reusable after the grace period; reusable slots can be reassigned to later playerIds. Capture a remote player's current transform before performing the PlaceAtMe-backed Stage 4 spawn and apply that transform immediately when the isolated proxy is promoted, preventing a brief visual spawn near the local player. Misc: improved logging/throttling, slot assignment/reassignment logic, and various helper functions. Docs updated (architecture.md, dev-log.md) and plugin/src/F4TProxyActorController.cpp implements the behavior.
Introduce a controller-local runtime proxy slot manager (ProxyActorSlot) and g_proxySlots map capped at kMaxRuntimeProxyActors = 4. Transition the proxy flow from a single active runtime proxy to per-remote-player slots: sorted remote snapshots, per-slot pre-spawn candidate snapshots, PlaceAtMe-backed spawn attempts (one in-progress spawn globally), isolation/settle/promotion of placed refs into slot.proxyHandle, per-slot movement smoothing/hold logic, and validation/restore of handles. Preserve the single placed fallback reference for one selected player and keep slots session-sticky (no reuse/despawn yet). Update docs (architecture.md, dev-log.md) and header/source (F4TProxyActorController.{h,cpp}) to reflect Stage 4 behavior and diagnostics.
Promote a single runtime-spawned proxy as the preferred active remote-player representation (Stage 3 / 3.7) while preserving the placed reference as a fallback. Updates include: detailed architecture and dev-log additions describing staged diagnostics (3.1–3.7), PlaceAtMe-backed spawn candidate isolation/settle, vanilla/Codsworth diagnostics, console PlaceAtMe testing, near-player visibility holds, and PASS/PARTIAL/FAIL diagnostic outcomes.
Code changes (plugin/include & plugin/src): adjust header comment and implement numerous runtime proxy features and diagnostics: new constants, enums, structs, state variables, logging helpers, position/distance helpers, absolute FormID lookup, runtime actor base selection (custom vs vanilla), PlaceAtMe-backed spawn state machine, debug placement/hold timing, candidate snapshot/isolation, promotion to active runtime proxy, and many throttled/logged diagnostics. The placed CK reference remains the fallback if runtime spawn/validation fails. Docs changed: docs/architecture.md and docs/dev-log.md updated to describe the new Stage 3 behavior and testing notes.
Files changed: docs/architecture.md, docs/dev-log.md, plugin/include/F4TProxyActorController.h, plugin/src/F4TProxyActorController.cpp.
Behavioral notes: single-proxy only (Stage 4 mapping deferred), extensive diagnostic logging added, and in-game validation/testing remains pending.
Introduce a Stage 2 diagnostic that attempts a single runtime spawn of F4T_RemotePlayerProxy in F4TTestCell01 from the game-thread proxy controller. Changes include a new enable flag (kEnableRuntimeProxySpawnDiagnostic), diagnostic offset constant, new diagnostic ObjectRefHandle and boolean state flags, and a TrySpawnRuntimeProxyDiagnostic function that builds NEW_REFR_DATA, calls TESDataHandler::CreateReferenceAtLocation, validates the returned handle/actor/cell, logs a single attempt and success/failure outcome, and intentionally leaves the spawned actor in place. The diagnostic spawn is run before placed-proxy lookup and the spawned reference is skipped during placed proxy scanning so the placed proxy remains the active visual fallback. Updated header comment and documentation (architecture.md and dev-log.md) to describe the new diagnostic behavior and testing notes.
Introduce Stage 1 runtime lookup diagnostics for the proxy actor base: adds ResolveProxyActorBase and ResolveProxyActorBaseByPluginLocalFormId along with helper checks (IsTestPluginLoaded, IsUsableProxyActorBase, editor/fullname helpers). The code logs plugin load status, editor-ID resolution, and a plugin-local FormID fallback (0x0020A1) while refusing to spawn actors (runtime spawning remains disabled). Adds throttled and one-shot log flags to avoid spam and invokes the diagnostic early on the game-thread before placed-proxy fallback and remote-player selection. Documentation updated (docs/architecture.md and docs/dev-log.md) to record the new diagnostic behavior and next steps.
Add a temporary in-cell holding fallback for the single placed proxy actor when no valid same-cell remote player is available. Introduces kProxyHiddenHoldingPosition, ProxyLifecycleState, RemotePlayerSelection, MoveProxyToHoldingPosition and RestoreProxyForRemotePlayer, plus selection/state-tracking and throttled logs. The controller now moves the proxy to the hidden position on disconnect, disappearance, or cell-mismatch and snaps it back when a valid same-cell remote appears. Documentation and dev log updated to describe the lifecycle and rationale (docs/architecture.md, docs/dev-log.md, protocol/player-sync.md).
Add optional movement-state fields (isMoving, isSprinting, isSneaking, isJumping, weaponDrawn, movementSpeed) to transform packets and wire them end-to-end. Plugin changes: extend F4TNetworking API and RemotePlayerState, derive movement speed/jump state on the game-thread, validate values, include fields when formatting transform JSON, and add throttled remote movement-state logging. main.cpp adds sampling, speed/vertical calculations, jump hold logic, and change-detection to avoid extra sends. Networking parsing (F4TNetworking.cpp) reads optional booleans/floats safely, preserves backwards compatibility, and clears movement-state logs on disconnect. Proxy controller includes a TODO note for future animation use. Server and docs: update protocol and packet docs, dev-log, server README, and fake_client.py to parse/display optional fields safely. Also add several .cursor rule files for coding, documentation, protocol, project overview, and testing guidance. This milestone prepares the data model for later animation/behavior work while keeping existing relay behavior unchanged.
Separate normal transform send cadence from movement logging and improve proxy smoothing. Key changes:
- Polling/send logic (plugin/src/main.cpp): introduced distinct send vs log intervals (100ms send, 1s log), lowered send thresholds (≈3.0 units position, 0.02 rad rotation), renamed/clarified functions, and added special movement types (worldspace_change, cell_change, teleport) that bypass the send gate and are logged immediately. Normal movement targets roughly 10 Hz while moving to avoid packet-per-frame traffic.
- Proxy controller (plugin/src/F4TProxyActorController.cpp): tuned proxy position lerp alpha to 0.15 for smoother motion, renamed movement-interval variables for clarity, and removed the generic per-update movement gate so normal proxy visual updates are applied each game update while only the safety-offset path is throttled.
- Documentation updates (docs/architecture.md, docs/dev-log.md, protocol/player-sync.md): describe the new send/log separation, cadence and thresholds, smoothing behavior, and recorded dev-log about smoothing tests and results.
These changes reduce network noise, produce smoother remote visuals, and keep readable local movement logs while preserving immediate sends for large/categorical movement changes.
Introduce simple position smoothing for normal proxy movement and snap special movements. Adds kProxyPositionLerpAlpha, Lerp/LerpPosition helpers, and ShouldSnapRemoteMovement to lerp proxy position on normal updates while snapping on cell_change, worldspace_change, and teleport. Update MoveProxyToRemotePlayer to use lerp or snap, keep heading snapping (TODO: wrapped angle smoothing), and add throttled/readable logs for smoothing start, first smoothed movement, snaps, and idle-on-cell-mismatch. Minor messaging change on disconnect to leave proxy idle at last position. Update docs (architecture, setup, protocol) and dev log to reflect the new behavior and testing notes; dynamic spawning/multiple proxies remain out of scope.
Enable game-thread proxy actor movement driven by a copied remote-player snapshot and update related networking/validation, docs, and test client.
- Plugin: add F4T::ProxyActorController::Update() (alias UpdateSafetyTest preserved) and implement remote-state-driven movement for the single placed proxy (F4TProxyRemotePlayer01REF) in F4TTestCell01. Selects lowest available playerId, validates same-cell/worldspace for movement, and caches represented playerId. Adds helper functions (ParseHexFormId, IsRemotePlayerInSameLocation, SelectRemotePlayerToRepresent, MoveProxyToRemotePlayer) and improved throttled logging.
- Networking: tighten transform packet required-field checking (requires type, playerId, x, y, z, angleZ, cellId), add GetMissingRequiredTransformField, make movementType/worldspaceId/clientTime/serverTime optional with sensible defaults, and switch LogThrottledWarning to accept string_view.
- main.cpp: call ProxyActorController::Update on game-thread tasks.
- fake_client.py: mirror new packet validation and provide defaults for optional fields.
- Docs/dev-log/protocol/setup: update architecture, dev log, protocol, and setup notes to describe the single-proxy remote-state milestone, required packet fields, and testing checklist.
This change keeps networking thread limited to parsing/updating plain remote-player state and moves all actor access to the game-thread controller. Dynamic spawning, multiple proxies, and interpolation remain out of scope.
Add a networking receive loop and in-plugin remote-player storage. Introduces F4TRemotePlayerState (header + implementation) to track assigned playerId and remote player snapshots with thread-safe access. Expands F4TNetworking to start/stop a background receive thread, parse newline-separated JSON packets (welcome, transform, disconnect), validate fields, update remote state, throttle logs, and handle socket/thread synchronization. Add nlohmann_json to xmake and plugin build. Update docs and dev log to reflect the new receive behavior and current prototype scope.
Expand documentation to describe the current local networking prototype and its protocol. Adds a Current Architecture section and Fake Client responsibilities, clarifies that the Fallout 4 plugin currently only sends transforms (no receive loop yet), and documents implemented message types (welcome, transform, disconnect) with packet field descriptions and examples. Update player-sync and packets docs to reflect movementType, server/client timestamps, and the in-memory remote player state model used by server/fake_client.py. Flesh out server/README with run/test flow and implemented behavior. Revise dev-log with milestone entries, testing notes, and an entry template for future updates.
andrew
