code-map.md

Code map

One folder, one concept, named after it. src/votv-coop/src/ holds the implementation and src/votv-coop/include/ the headers, in the same layout. Paths below are relative to src/votv-coop/src/; a name without an extension is a .cpp/.h pair.

The layers, top to bottom

Layer	Folder	Owns	Never contains
gameplay and network	coop/	elements, sync lanes, sessions, players, the wire protocol	reflection or engine-memory access (it goes through ue_wrap/)
what the player sees	ui/	the menus, the server browser, the HUD, the F1 overlay	network state
the player's language	l10n/	the catalogues of the mod's own text, the lookups, the formatter	anything of coop/ or ui/ (they call it)
boot glue and tests	harness/	the scenario runner and the scripted test scenarios	gameplay logic
engine wrapper	ue_wrap/	reflection, signatures, hooks, the game-thread pump, one wrapper per engine or game class	network, gameplay or co-op state
the loader contract	loader/, bootstrap/	start_mod() as UE4SS calls it, DllMain, the refuse dialog	everything else

coop/ — gameplay and network

Folder	Concept	Key files
coop/net/	transport, sessions, admission, the wire protocol	protocol.h (every message kind and the build number), session (GameNetworkingSockets host and client, four peers, the lanes) with session_streams (the unreliable per-tick streams), stream_slot + remote_streams (what a peer keeps of each stream it receives: the newest value behind a sequence latch, grouped by the owner whose edge resets it) and outbound_streams (what it sends, reset whole at a session's start), eid_pose_lane (the host-originated pose lanes keyed by element id, the send queue and the receive merge) and session_* send helpers, session_start (LAN or P2P entry), session_serial (a serial per session start), signaling_client + ice_config (NAT traversal through the master server) with signaling_proof (the Ed25519 answer to the relay's registration challenge, its own file because the bytes are a contract with the relay and the release gate), lobby_client + lobby_announcer (the server browser's list) with master_slots (which masters there are and which one is chosen), peer_identity + peer_admission + lobby_password (the Ed25519 identity, the mutual challenge, the password), connect_history (the per-source history primitive, one instance for the connection cap and one for the password-guess bound), intent_bucket (a client's budget of intents on the host, one per sender slot), latest_wins (a client's changes of one display state on the host, applied at a pace with the newest kept), end_reason (the stable code a close carries), send_backlog (a reliable send is delivered or the connection dies), blob_chunks (large transfers), http_client
coop/dispatch/	routing of reliable messages	event_feed drains and dispatches; event_dispatch_entity, _state, _signal, _intent, _world are the five family routers, each owning its message kinds
coop/session/	the per-tick orchestrator and the join	net_pump (connect and disconnect edges, announcements), session_manager, player_handshake with _version (the game+build gate), _nick, _prefs, _roster (the Join and PlayerJoined messages), join_seed, join_progress, world_load_episode, host_mode, pause_guard (no pause while connected), shutdown, teleport_client, subsystems, world_ready_answer (the host's answer to a client's ClientWorldReady: first completes the join, a repeat flood is rate-capped then ended), local_grants (this machine's local dev grants) and grants_sync (their projection from the host, kind 168)
coop/element/	entity identity and lifecycle: the one owner of eid to actor	registry, element, mirror_manager + mirror_managers, identity_create (create-or-adopt a mirror), identity_destroy (retire one), element_deleter (deferred destroy), death_seam (an element's end of play, or a subscribed class's, announced once to the lanes that subscribed), portable_identity (a name both peers compute for an actor the save does not key), intent_authority, object_scan_hub (the one pass over the object index that every index consumer rides), quiescence_drain, mirror_defer, lerp_window, and the element kinds prop, npc, player, world_actor
coop/player/	remote players and per-player state	remote_player + remote_player_ragdoll, puppet_drive, puppet_carry_drive, puppet_body_yaw, puppet_footsteps (driving the engine pawn), players_registry, player_profile_store (the host's copy of every player's profile: held in memory, cut to disk with the world save), roster + roster_ledger (who is in each slot), nickname_arbiter, nick_color, nameplate, hand_item, local_body, local_streams, client_model + skin_registry + skin_preview + skin_effects (skins), movement_ledger, player_damage, death_revive + run_end_travel (a trip to the menu the player did not ask for is refused and answered with a revive), ragdoll_gate, sleep_sync, item_activate, flashlight_click_sound, stat_orders (an admin's order to, and query of, one player's stats and effects) + stat_orders_wire (their bytes, their checks, and the table of the ones awaiting an answer)
coop/props/	physics props, piles and trash	prop_lifecycle (the destroy seam), prop_snapshot + snapshot_census (the connect snapshot), remote_prop with _spawn, _convert, _physics, _destroy (the receivers), host_spawn_watcher, prop_key_index (every live keyed prop by key, for a key on the wire; its key reads are ue_wrap/actors/prop_keys) + prop_tracked_keys (the props this peer tracks by key), prop_synth_key, save_identity_bind + save_identity_map (bind save-loaded actors to host eids in the join window), pile_spawn_bind, trash_mirror (the client's mirror of either trash form, the game's own actor parked), trash_morph_gate (the verbs a client refuses so it never authors a transition), trash_sweep (the clumps a broom stroke sets rolling: their ids at birth, a carry nobody holds, the roll), trash_channel, trash_grab_intent, trash_collect_sync, trash_pile_sync, trash_use_intercept, trash_clump_pose_stream, prop_drop_intent, prop_spawn_authoring (did a PLAYER's spawn verb author this birth, or the world's own churn -- the fact the drop-intent seam admits a catalog spawn on), prop_save_data (each prop's own save record, by Key), prop_stick_sync, container_contents_sync + container_write_policy (a world container slice, and the host arbitration a client-authored one passes) + container_park (the holding pen for a slice whose container has not arrived yet) + container_birth (a container that changes hands through the world: the thrower's slice, the host's awaited copy) + container_view_close (a player's view into a container ends where the player's reach does), grab_observer, registry_reaper, join_membership_sweep, unresolved_pose_ledger, prop_echo_suppress, prop_wire_parity, prop_census, prop_container_extract, prop_destroy_seam, prop_fresh_spawn, prop_element_tracker, prop_sound, active_drive
coop/creatures/	NPCs and creatures	npc_sync + npc_sync_install (the spawn seam), npc_mirror, npc_adoption, npc_pose_host, npc_pose_drive, npc_world_enum, kerfur_convert with _host and _client, kerfur_entity, kerfur_reconcile, kerfur_prop_adoption, kerfur_command, kerfur_menu_input, kerfur_form_assembler (the prop-to-NPC conversion cycle), owner_entity_sync (creatures whose AI reads the local player: owned per peer, visible to all), piramid_sync, roach_sync, wisp_attack_sync, wisp_grab_hold, wisp_tear_mirror
coop/interactables/	keyed device state	doors, lights, light groups, containers, garage, appliances, lockers: interactable_sync + interactable_channel; keypad_sync + keypad_verbs, verb_lanes (the lanes on a device's own verbs at the script gate, wired in one place), toggle_verbs (a symmetric device's state at the verb that writes it), window_sync, grime_sync, turbine_sync, drone_sync, device_occupancy, garbage_sync. The signal workstation: signal_sync, signal_catch_sync, signal_wire, dish_sync, dish_calib_sync, download_arm_sync (the download's arm and reset, the host's), desk_input_sync, desk_sim_sync, desk_ping_sync (the ping's verdict, rolled on the host), desk_verb_intent and desk_verb_effects (the desk's save-family presses, run by the host, their gloss, stat and sounds sent to the presser), desk_cursor_sync, desk_snd_fx, deck_play_sync, comp_sync (the refiner's decode, the host's), console_state_sync, drive_sync, drive_payload_sync (a drive's row, the host's), eraser_press_intent (the eraser's delete, run by the host), drive_rack_sync, tape_caddy_sync, physmods_sync, serverbox_sync, server_upgrade_sync (a server box's physical upgrades), sat_console_sync and sat_console_table (the SAT console's shared commands, run on a terminal the host keeps for each typist, and which command runs where), laptop_sync, portable_pc_lid (the portable PC's lid, on its own verb), laptop_buffer_sync, floppybox_sync, floppy_slot_sync and floppy_slot_entry (a device's disc slot: the state, and which overlap into it counts as an insert), meadow_db_sync, meadow_db_writers, meadow_db_join, meadow_db_park and meadow_db_hash (the laptop's signal database, the bodies that write it, a joiner's seed of it, its inbound lines that cannot apply yet, and the database as content hashes). The ATV: atv_sync, atv_runtime_mirror (a client's mirror of a runtime ATV, its spawn and destroy), atv_spawn_park (a runtime ATV's spawn held until its world is ready), atv_corrector, atv_hit_guard, atv_condition_sync
coop/world/	global and ambient state	time_sync, sky_sync, weather_sync with weather_rain, weather_fog, weather_lightning, weather_redsky, weather_event_births, firefly_sync, spawn_authority (shared-world spawners run on the host only), event_fire_sync + event_fire_policy (which received fire a client replays), event_active_sync, event_cue_sync, alarm_sync, balance_sync, email_sync, daily_task_sync, power_grid (the generators run on the host) + power_decay (their wear dice) + power_puzzle (their repair puzzles) + power_upgrade (the upgrades an install spent) + power_panel (the panel's one author), world_actor_sync + world_actor_mirror
coop/items/	inventory, the economy, and the deployed items	player_inventory_sync + inventory_wire, inventory_pickup_sync, order_sync (shop orders: the client names the row, the host performs and prices it) + order_queue_sync (the host's delivery queue mirrored on the clients) + order_rows (an order's items on the wire), coingun_sync + coingun_arbiter + coingun_collect (the sell gun and its coins), save_record_wire, hook_sync + hook_anchor + hook_prop_claim + hook_constraint (the grappling hook and the rope: the owner's stream and the mirrors, the anchor handoff, the props its ties claim, and the tie itself, which lives on the host), broom_stroke + broom_push (the broom: every stroke is the host's, a client's queued with what it read of its holder, and what a stroke pushes or knocks out of a dispenser streams)
coop/comms/	text chat	chat_sync, chat_rate (how fast a client may speak, judged on the host: Source's interval and two-tier bucket), chat_feed, chat_bubbles, chat_log, chat_nick_color, peer_action_feed
coop/commands/	commands typed in chat, run on the host	command_line (splits a line), command_targets (who a word names), command_registry (the commands and their nodes), command_dispatcher (one line to one verb), command_args (an argument word's parsers: a whole number, true or false, a duration), action_source (who an admin action is recorded as), command_sync (the transport: the chat route, the two wire kinds, the player record), moderation_commands (/kick, /ban, /banid, /unban, /tphere: the handlers call the moderation verbs through ports), settings_commands (/set, /reset: a server setting named by its key, through ports onto the config setters), mv_commands (/mv: the permission store edited in game, LuckPerms' /lp shape), mv_info (the lines of info and listgroups)
coop/voice/	voice chat	voice_capture, voice_chat, voice_playback (Opus, 3D positional)
coop/moderation/	kick, and bans by player id and address	moderation, ban_list, seen_players
coop/permissions/	who may ask the host for what (LuckPerms' model)	context_set, node + node_map (a holder's nodes), model + inheritance (users, groups, parents), resolution (a player's resolved answers), permission_files (the store's files: read, loaded, written one holder at a time), permission_edit (an edit of one holder, planned through the loader), action_log (the action log's record and its writer), permission_host (the hosted server's live model), grants_core (the projected table and its rules)
coop/save/	the host owns the save	save_transfer (streams the host's world to a joiner), slot_file_read (a slot file read once it holds still), save_guard, save_block, save_button_disable, save_indicator_suppress
coop/server_profile/	the server a host runs, as a folder beside the game	server_profile (a server's id, the hosted server's folder, its creation at a host start)
coop/game_build/	which game build this process runs, and what it means for this Multivoid	game_build (the target, a known newer or older build, or one no row names; the [dev] game_build_force drill arm; the popup's remembered answer; the key the Join and the lobby carry), last_builds.inc (the last Multivoid build for each game version left behind)
coop/text/	text encoding and names	utf8_codec (the one owner of decoding), repertoire + repertoire_ranges (what this build can draw), case_fold, mark_ranges, ignorable_ranges, exclude_ranges, novelty_ledger
coop/config/	the ini	config, config_registry + config_registry_rows (every key is a registered row with a description), config_ini_write, config_review, config_selftest
coop/atomic_file/	a file written whole: beside itself, flushed, moved in one step	atomic_file (the writer and its selftest)
coop/input/	who owns the keyboard	input_owner (the game, a text field, or the overlay)
coop/dev/	developer features and probes, ini-gated, off by default	freecam, pos_hud, set_clock, spawn_npc, force_weather, event_force, event_trigger, the *_probe, *_watch and *_selftest instruments and the *_drill drivers, perf_probe; dev/director/ drives a player through a test scenario

ui/ — what the player sees

Concept	Files
the Multiplayer menu	multiplayer_menu, host_window_native, host_save_picker, host_session_settings, host_session_choices, browser_input_screens, end_reason_dialog, boot_warning_dialog, game_build_dialog (the popup naming a game this Multivoid was not made for), menu_sfx
the server browser	server_browser_native with server_browser_rows, server_browser_actions, server_browser_panels, server_browser_surface (which browser is open) and server_browser_selftest; server_browser is the ImGui fallback
the native UI kit	native_screen, native_text_field, style, scale, link_format
in-game surfaces	hud (nameplates, chat, the event feed), chat_input, chat_view, scoreboard, loading_screen, join_curtain, voice_icons
the F1 overlay	imgui_overlay, overlay_backend with overlay_backend_dx11, overlay_backend_dx12, overlay_backend_dx12_capture, overlay_cursor, overlay_diag, overlay_test_arm, fonts, atlas_watch, input_focus
overlay panels	dev_menu (its developer panes in dev_panes), admin_panel, skins_panel, voice_panel, world_rules_panel, server_settings_pane, bug_report_pane, config_review_panel, net_stats_panel, console

l10n/ — the player's language

l10n (the lookups T, Tc, Tn, Label, Fmt, and Init, which builds the one catalogue; the markers in mark), po_reader (a gettext .po file read, the only parser of a translator's text), plural_expr (a catalogue's plural rule, compiled once), printf_check (the conversions a message may carry), fmt (the positional formatter), catalog, locale_choice and quiet -- these and the three before them private to src/l10n/ -- l10n_selftest. The packs the mod ships are src/votv-coop/locale/<ll_CC>.po, embedded by name, beside the template multivoid.pot that .github/ci/l10n_pot.py extracts and gates (the files that may hold player text are its allowlist); .github/ci/l10n_vectors.py writes the selftest's plural vectors.

harness/ — boot glue and scripted tests

harness (the scenario runner), session_runtime, autotest + autotest_dispatch and harness/autotest/ (one file per scenario: join churn, grab, ragdoll, weather, events, death, damage, pause guard, save UI, scan parity and more), sdk_check, fingerprint_census + fingerprint_capture (every watched or hooked game function checked against the build the mod was made for, bytecode-fingerprint.md; the dev capture), compat_report (the report file every check writes, and its one verdict), compat_boot (its sections the boot writes: the game build that runs, and the engine's checks with every search of the game's code), screenshot, mod_environment, harness_diag, browser_click_arm (the test variables that open the browser, host and join as a player's click does). The launcher drives these from outside the game.

ue_wrap/ — the engine wrapper

Folder	Concept	Key files
ue_wrap/core/	the substrate	sig_scan (AOB resolution of GUObjectArray, GNames, ProcessEvent), reflection + reflection_props + reflected_offset (classes, properties, functions), uobject_listeners + object_index (the engine's object-created and object-deleted notifications, and the per-class index of live objects they keep), call (calling a reflected function), hook + pe_detour + ufunction_hook (the MinHook ProcessEvent detour and per-function interceptors), script_gate + script_gate_names (a detour on the VM's script loop: a Blueprint function body observed and cancelled per call, with its arguments and its caller, on every route; the name watches in a file of their own), script_bytecode + script_fingerprint (a function's compiled bytecode read as canonical text and fingerprinted), game_thread (the posted-task pump; engine calls happen only there), cached_obj_ref + gc_pin (object lifetime across worlds), sdk_profile + sdk_profile_names (the per-game-version offsets and names), game_build (which game build runs: the executable's link stamp and the pak's index hash, matched against ue_wrap/facts/game_builds.inc), scan_ledger (every search of the game's code, found, missed or not tried), fname_utils, fstring_utils, ftext_utils, field_io, engine_heap, asset_load, hot_path_guard, walk_timer, walk_census (how often the finders walk the whole object array, and from which call sites), log, trace, paths, types, hook_drill, pe_diag
ue_wrap/facts/	the game facts the mod depends on	function_row (every watched or hooked game function, declared as a row in the file that registers it; the registration APIs take only rows), fingerprints_<target>.inc (the generated reference table of the target build)
ue_wrap/engine/	engine objects	engine (world, actors, spawning), engine_pawn, engine_component, engine_widget + umg_build (UMG), engine_bones, engine_attach, engine_audio, engine_nav, data_table (a data table's rows, walked in memory and read by column through the engine), engine_save + save_capture + save_to_slot_hook (the one detour on the engine's save function: a gate before a world save, a notice after) + save_browser + gvas_meta (save files), engine_mainplayer, engine_playerragdoll, spawn_gate, actor_end_play (the detour on the engine's AActor::EndPlay: every actor that began play, ending it, with the reason), spawn_menu, scs_rig, world_identity (which world is current)
ue_wrap/actors/	the game's actor classes	puppet + puppet_spawn, prop, kerfur, wisp, inventory, vitals (the player's stats, one table, and the profile snapshot), effects (the player's status effects: the game's list, add, remove, and reset out of a joiner's save), sleep, swinger, save_record (the Fstruct_save codec, and the actor's own getData/loadData), floppy_disc, begin_equipment, broom, container_openers (the actors a far-standing container is opened through: the drone, its sack, the ATV), container_view (the local player's inventory screen: the container it shows, and the game's own close)
ue_wrap/devices/	keyed devices	door, door_box, lightswitch, passwordlock, power_control, garage, appliance, base_window, grime, windturbine, drone + drone_console (its garage console, keyed by no lane: the host finds it by the presser's reach), atv + atv_condition, laptop, portable_pc, floppybox, serverbox
ue_wrap/desk/	the signal workstation	dish, dish_writers (the toolgun's calibration tool and the uncalibrator), console_desk, desk_ping (the ping machine and its verdict), sat_console (the SAT console's terminal), coords_panel, coord_tower (the three triangulation towers), comp_pane, device_screen, drive_chain, tape_caddy, phys_mods, saved_signals, meadow_store, signal_dynamic, space_renderer, desk_audio, daily_task
ue_wrap/world/	world singletons	world_singleton (one live instance of a class the game keeps one of, from the object index, of the running world), world_instances (every such instance of a class a level places several of, judged by the same rule), daynightcycle, active_events (the gamemode's running-event refcount and its senders), skysphere, jellyfish_path (the space jellyfish's path and its fish), red_sky (the gamemode's red sky toggle and its event), directionalwind, game_rules, game_mode (the mode enum and the running world's mode byte), economy, order_economy, store_catalog, weapon_catalog (what one swing of a held item can deal), email, votv_lib

loader/ and bootstrap/

loader/cppmod_entry exports start_mod() and uninstall_mod(), the two functions the UE4SS mod scan calls, and refuses to start beside a leftover pre-mod-folder install; cppmod_stubs.asm carries the stubs. bootstrap/dllmain, boot and refuse_dialog are the process entry and the one dialog the mod can show before the game's UI exists.

Adding a sync lane

1. Decide who owns the state (see architecture.md): the host owns it and clients mirror; a client names an intent and the host performs it; or each peer owns its own copy and the rest see it.
2. Add the message kind to coop/net/protocol.h and bump the build number: the wire changed.
3. Route it in the family router that owns its kind in coop/dispatch/.
4. Own it in one file, in the folder of its concept. The late-join answer (what a peer who joins mid-way receives) lives in the same file.
5. Add its row to the subsystem's doc, and a driver under coop/dev/ behind a registered config flag when the lane can be exercised without hands (*_selftest is the shape).