The core
One engine,
every game.
The core is the shared engine behind every JustAddMP mod. It does all the work that is the same in every game: it starts the game with co-op built in, connects players through Steam or by IP, runs Steam lobbies and invites, keeps the host in charge of the session, draws the co-op menus and the status overlay in the game, writes crash reports, and lets you start the game straight from Steam if you prefer.
So each game only has to add its own part: how its players, cars, missions and menus are synced. A fix or a new feature in the core reaches every game, and each game picks the core version it was tested with, so an update never breaks a game by surprise.
What it does
The parts every game needs
Game launcher
Finds the game in your Steam library, checks it's a version the mod supports and starts it with co-op built in.
Start from Steam
If you prefer, install it once and co-op starts every time you press Play in Steam. Uninstall puts the game back as it was.
Steam or IP
Players connect through Steam, no ports to open, or straight by IP address. No separate server: one player hosts.
Lobbies and invites
Host a game, invite friends through Steam, and they join from the invite or their friends list. Friends can also drop in mid-session.
Host-run sessions
The host runs the session and passes everything on, so everyone sees the same game. Players on a different version are turned away with a clear message.
Pre-game lobby
Everyone readies up, the host picks what to play and starts it for all at once. Late joiners can follow a game already running.
Password, kick and ban
Lock a session with a password, and kick or ban a player from the co-op menu. Bans cover both the IP address and the Steam account.
Co-op menus in the game
Co-op entries in the game's own menus, co-op panels, join and leave banners and a settings page, usable with keyboard, mouse or gamepad.
Status overlay
A small overlay drawn over the game that shows the co-op status, with live traffic numbers when you turn on the debug view.
Instant leave notice
When a player quits, the others are told straight away; a crashed or killed game is noticed within about 4.5 seconds.
Only what matters is sent
Nearby things are updated more often than far-away ones, and each player gets a fair share of the connection.
Natural movement of other players
Other players' characters walk, run and sprint with the game's own animations at their real speed, and their cars steer and brake like the driver's, instead of being dragged into place.
Crash reports
If the game crashes, a crash report is saved so the problem can be found and fixed.
Join a friend
A Join Friend list in the co-op menu shows your Steam friends who play the game and what they're doing: hosting, in a friend's game, full or on another version. Pick one to join; the version is checked before you connect.
Automatic reconnect
When a player's connection drops, his game keeps running and rejoins the host on its own for up to a minute, and he gets his place back. The others see that he is reconnecting.
Low latency
Updates leave in the same frame they're made, lost ones are resent after about one round trip, separate kinds of updates don't hold each other up, and the bulky ones give way when the connection is full. Other players are shown with a delay that adapts to the connection.
Sync recording
Every co-op session keeps a detailed record of what each game sent, received and did, so after a test the two games can be lined up and compared to find exactly where they drifted apart.
Works with
- 64-bit Windows games
- Games that draw with DirectX 11
- With or without Steam (without it, friends join by IP)
The games
Built on the core
Each game picks the core version it was tested with and moves to a newer one on purpose, so a core update never breaks a game by surprise.
- Mafia: Definitive EditionBetacore v0.14.1
- Mafia II: Definitive EditionIn progresswill use the core
- Mafia III: Definitive EditionPlannedwill use the core
- Mafia: The Old CountryPlannedwill use the core
- Fallout 3Plannedwill use the core
- Fallout: New VegasPlannedwill use the core
- Fallout 4Plannedwill use the core
- The Elder Scrolls III: MorrowindPlannedwill use the core
- The Elder Scrolls IV: Oblivion RemasteredPlannedwill use the core
- The Elder Scrolls V: Skyrim Special EditionPlannedwill use the core
- Sleeping Dogs: Definitive EditionPlannedwill use the core
- Mad MaxPlannedwill use the core
- Middle-earth: Shadow of MordorPlannedwill use the core
- Middle-earth: Shadow of WarPlannedwill use the core
- Assassin's Creed OriginsPlannedwill use the core
- Assassin's Creed OdysseyPlannedwill use the core
- Batman: Arkham KnightPlannedwill use the core
- Kingdom Come: DeliverancePlannedwill use the core
- Days GonePlannedwill use the core
- The Witcher 3: Wild HuntPlannedwill use the core
- Cyberpunk 2077Plannedwill use the core
- Marvel's Spider-Man RemasteredPlannedwill use the core
- Horizon Zero Dawn RemasteredPlannedwill use the core
- Horizon Forbidden WestPlannedwill use the core
- HITMAN World of AssassinationPlannedwill use the core
Progress
Where the core is at
Progress
30 of 44 tasks done
68%
- LauncherDone
- Networking8/12
- Sessions6/7
- In-game menus & overlay8/11
- Crash reports & logs4/5
- More games0/5
Last commit
Launcher
Done- Done: Game Launcher
- Done: Game Version Check
- Done: Launch from Steam
- Done: Launcher Input Checks
Networking
8/12- Done: Networking
- Done: Steam Lobbies & Invites
- Done: Host-Run Sessions
- Done: Safer Steam Joins
- Done: Nearby-First Updates
- Done: Traffic Statistics
- Done: Higher Bandwidth Limits
- Done: Faster Dropped-Game Detection
- To do: Natural Remote MovementTested on two PCs; rebuilt in v0.12.0 with one smoothing and correction layer for players, cars and NPCs, waiting for a two-PC test
- To do: One Owner per Car and CharacterIn v0.12.0: the nearest player owns the traffic and people around them, with smooth hand-overs, waiting for a two-PC test
- To do: Automatic ReconnectTested on one PC: back in the same slot within a second; Steam test to do
- To do: Lower LatencyIn v0.11.0: lanes, send priorities, a shared session clock and an adaptive delay; 26-34 ms in the first two-PC test, more play to do
Sessions
6/7- Done: Session Password
- Done: Kick Players
- Done: Kick & Ban
- Done: Spam Protection
- Done: Pre-game Lobby
- Done: Instant Disconnect Notice
- To do: Join Friend PanelPanel tested on one PC; joining a friend needs two PCs
In-game menus & overlay
8/11- Done: Status Overlay
- Done: Overlay Resize Safety
- Done: Co-op Panels & Banners
- Done: Entries in the Game's Own Menus
- Done: Game Options in the Co-op Menu
- Done: Co-op Settings Page
- To do: Update NoticesIn v0.13.0: the main menu tells you when a newer version is out, checked against justaddmp.com; waiting for an in-game check
- Done: Saved Settings
- Done: Drawing for Name Tags
- To do: Real Gamepads in the Co-op MenusIn v0.11.0, waiting for a test with a real controller
- To do: Gamepad Button PromptsTested in the lobby and friends panel; text boxes still to check. The keyboard no longer stays blocked after a pad button closes a panel (fixed in v0.11.0, waiting for a test)
Crash reports & logs
4/5- Done: Crash Reports
- Done: Reliable Crash Dumps
- Done: Sync Recording
- Done: Last Five Logs Kept
- To do: Session Log ZipsIn v0.14.0: every session writes one zip with its logs, settings and timing records to send after you play; worked on one PC, waiting for a two-PC test
More games
0/5- To do: DirectX 8 GamesPlanned: Morrowind
- To do: DirectX 9 GamesPlanned: Fallout 3, New Vegas
- To do: DirectX 12 GamesPlanned: Oblivion Remastered, The Old Country, Cyberpunk 2077, Spider-Man, Horizon, Hitman
- To do: Vulkan GamesPlanned
- To do: 32-bit GamesPlanned: Fallout 3, New Vegas, Morrowind
Releases
Version history
- v0.10.0LatestA detailed record of every co-op session for comparing two games, the last five logs kept, and fixes from the first two-PC test: other players' cars get their speed back so they can roll, and sprinting characters keep up.
- v0.9.0Groundwork for natural movement: other players' characters walk at their real speed instead of sliding, and their cars use the driver's steering. A name given for a test run is no longer saved as your name.
- v0.8.0A crashed or killed game is noticed in about 4.5 seconds instead of 10, without dropping a player whose game is just busy loading.
- v0.7.0Behind-the-scenes testing help for the co-op menus. Nothing changes for players.
- v0.6.0Live traffic numbers on the debug overlay, and much higher bandwidth limits so busy scenes are never cut short.
- v0.5.0The pre-game lobby, a co-op settings page, drawing for name tags, and an instant notice when a player leaves.
- v0.4.0Game options such as character and outfit in the co-op menu, settings that are saved, and a fix for menus that jumped back to the middle row.
- v0.3.0Kick and ban players from the co-op menu.
- v0.2.0Stability: safer Steam joins, more reliable crash reports, protection against spam, and clearer launcher errors.
- v0.1.0First release, split out of the Mafia: Definitive Edition mod: launcher, networking, Steam lobbies and invites, overlay and crash reports.
Git history
Latest commits
- core: v0.14.1 (one-PC test tools: --net-sim simulated lag on the UDP transport, --window-area, test input text; session_log test timing; used for the one-PC checks of MafiaCoop 0.17.1; protocol stays 9)678df32
- core: tests/session_log.cpp runs 11.5 s for its two SCK records (10.6 s left one out about 1 run in 7)58cbad7
- core: CHANGELOG (test input text)c3ac12e
- core: test input 'text <chars>' (typed characters for our panels' text boxes; the one-PC rejoin types the host's IP into JOIN BY IP)aee08f9
- core: one-PC test tools: --net-sim (simulated lag on the UDP transport) and --window-area407c0a1
- core: v0.14.0 (session diagnostics: session_log start block / SES / SCK / SUM / FIN, core/diag, core/bundle + zip_writer session zips with -recovered ones, log rate limiting and ten kept runs, trace caps 1 GiB / 4 GiB; LocomotionController::Applied from feat/foot-track; checked on one PC with MafiaCoop 0.17.0; protocol stays 9)cce1b28
- Session diagnostics: dll/session_log (a session start block in the log and SES records: versions, exe CRC, role, Steam, transport, every setting with passwords redacted, window / monitor, OS, fps, paths, every peer; SCK clock samples every 5 s; SUM every 10 s per peer and lane with the game's numbers and a summary log line every 60 s; FIN totals and an end block), core/diag (levels and counts a game layer publishes for them), core/bundle + core/zip_writer (one zip per session in logs\bundles: trace, main log, redacted ini, launcher logs, crash dumps, manifest; our own deflate, CRC-32 and zip container; a -recovered bundle at start for a session that did not end; newest 30 kept; the game exit waits up to 20 s for it), log: ten previous runs kept, warnings / errors rate limited per call site with a repeated-N-times line and counted, trace: 1 GiB per file, 4 GiB per folder, close hooks; tests zip_writer, session_diag, session_log, core_trace (not tagged; not verified in game)58e140b
- LocomotionController::Applied: a game layer with its own position fix tells the controller the nudge really applied, so the walk measurement (calibration) and the copy's walking velocity leave it out; test net_motion TestApplied (not tagged; WIP for v0.14.0)3e892eb
- core: v0.13.0 (update check: newest release from justaddmp.com once per game start, notice at the main menu; core_version.h minor fixed; protocol stays 9)e885919
- Update check: core/update_check (version parse and compare with pre-releases, endpoint answer, WinHTTP fetch on its own thread with 5 s timeouts, once per game start), GameInfo::updateId, a notice at the main menu and a line in CO-OP SETTINGS when a newer release is out, --update-as / --update-url for testing; test update_check8a8c4a4
- core: v0.12.0 (replication layer: replica, correction, authority; locomotion gait hint and hidden nudges; vehicle pin retry; protocol stays 9)287a4f6
- Merge feat/sync-core (replication layer: replica, correction, authority; locomotion gait hint and hidden nudges; vehicle pin retry)f91d03c
- docs/replication.md: the replication model (sender clock + playout clock per sender, interpolation, correction and its presets, locomotion gait hint and pin policy, NetRef, ownership epochs, region authority, a game-layer example); ARCHITECTURE.md pointer3afc8d8
- Replication layer: replica (SnapshotTrack / Stream: Hermite interpolation, teleport, bounded extrapolation, Present lead, per-sender playout clock), correction (one Corrector with foot / car / npc / traffic presets), authority (NetRef, OwnershipBook, RegionAuthority); LocomotionController: gait hint (the sender's gait), nudge with the correction rules (0.3 m dead zone, capped at max(0.15, 0.35 x speed) m/s), response-lag prediction, stop point, carry only while behind; VehicleController: pinned copies retried after 1.5 s doubling to 8 s, reset after 10 s kept up, pinnedFor / retryIn; tests net_replica and net_motion gait hint / pin policy583c7bd
- core: v0.11.0 (JOIN FRIEND, pad navigation and prompts, reconnect, lanes, send priorities, session clock, playout, pad guard and open friends fixes; protocol 9)8577314
- Test input script: open friends (JOIN FRIEND) accepted, as OpenForTest supports it; test test_input open panelsda17d80
- ui_input release guard: a held pad state older than 100 ms is read again by the guard (PadHold, dll/pad_hold.h), an unreadable pad counts as released; a game that stops polling XInput (loading screen) no longer keeps the keyboard blocked by the button that closed a panel; test pad_nav PadHoldb5cc90a
- Send priorities: Session::SetPriority (Critical / Normal / Bulk), per-peer send budget (sendBudgetBytesPerS, adapted to loss / reliable queue), bulk states thinned and bulk reliable deferred in lane order, counters thinned/deferred, NetMonitor lines; Session::onAppMessage (every app message with its age); Coop sets the budget from net_budget_kbps; tests net_latency priorities and onAppMessage; docsefd035a
- Lanes: lane 0 no longer waits for other lanes (a big or lost lane message does not hold back lane 0); once a connection uses a lane every reliable unit is laned, lane-0 ones too; lane messages still come after the lane-0 messages sent before them; tests and docsf596bdc
- Latency: app messages carry a send stamp (App flags bit1, u32 SessionTimeMs, kept by the relay): Session::MessageAgeMs/MessageStampMs in handlers, per-message age in MsgTraffic and NetMonitor (age N ms, fast resends, guest clock offset); tests net_latency message age direct and through the relaybed3b37
- README: net_latency test357194d
- Latency: net/playout.h (PlayoutClock: adaptive playout delay from arrival lateness, windowed-min offset, slewed render clock; Hermite, Extrapolate), UdpOptions::testDrop, tests net_latency (playout under jitter/loss/drift, Flush, fast retransmit, lanes, session clock) and net_loopback lanes under loss, docs protocol.md Latency / Lanes / Session clock / Playout7f42f9a
- Latency: Transport::Flush and Session::Flush (Coop::Tick flushes after SessionTick, pings flushed at once), reliable lanes (Transport::SendOnLane, Session::SetLane; UDP lane units with lane/laneSeq/barrier, Steam lane channels), UDP fast retransmit (RACK-like) and RTO floor 30 ms, Steam unreliable data NoDelay once pongs prove it, session clock (Pong u64 clock trailer, burst pings after a join, SessionTime/ClockSynced/ClockErrorMs); kProtocolVersion 9d8c6e30
- tests: four players - a full lobby (fifth refused, start waits for three guests, freed slot, host leave reaches all) and two guests lost at once coming back into their own slots (net_lobby, net_reconnect section 10)2991ffc
- core 0.11.0 (unreleased): version, kProtocolVersion 8 (reconnect trailers, PeerDropped), CHANGELOG (JOIN FRIEND, gamepad fixes, button prompts, reconnect), README test_input8c9c0fd
- Footer prompts shrink to fit the panel; X/Y/LB/RB held after a panel closes keep the game blocked like A/B (an X Start or Y Invite press does not reach the game)f2f15a5
- Panel footer prompts follow the input device like the games' menus: gamepad glyphs (A/B/X/Y, LB/RB, d-pad) after pad input, key names after keys/mouse (ui_prompts.h DeviceTracker, fed from every XInput read and the window messages, switches logged); one prompt list per panel drives both the footer and the pad's X/Y/LB/RB (lobby X Start/Ready/Join game, Y Invite; CO-OP panel Y Invite; JOIN FRIEND Y/F5 Refresh; text boxes X/Backspace Delete, Y/Ctrl+V Paste); PadNav reports X/Y/LB/RB presses; test dump and panel-open log show the footer; tests ui_prompts1d386e4
- Merge feat/reconnect: automatic reconnect (slot hold, resume token, PeerDropped)c3e0b9e
- Reconnect after a lost connection: the host holds a lost guest's slot (reconnectHoldS, PeerDropped 0x0D, DroppedPlayers), the guest keeps the session and rejoins the same address with backoff (Reconnecting state, reconnectWindowS) and gets his slot back with the resume token from the Welcome; PlayerInfo::joinSeq for Players() diffs (Lobby uses it); GameModule OnPlayerDropped / OnConnectionLost / OnReconnected; Coop notices, Steam lobby re-entry, panel status; net_reconnect tests; docsd7c8287
- JOIN FRIEND panel: Steam friends playing the game (net/steam_friends: GetFriendGamePlayed lobby, else rich presence connect; lobby data mc_version/mc_proto/mc_host/mc_state/mc_mode/mc_players/mc_max; hosting / in a friend's game / checking / not hosting / other version / full), Coop::GetFriends/RefreshFriends/JoinFriend, version check on lobby enter (invites too), EChatRoomEnterResponse in words, rich presence refreshed every 30 s; physical gamepad: every XInput user, empty slots probed once a second, connect/disconnect logged, PadNav (stick hysteresis + dominant axis, repeat, held-at-open ignored, B/START/BACK = back), unplugged pad no longer blocks the game, packet number bumped on block changes, DirectInput joysticks blocked with frozen axes; steam_flat friends exports + SetApiForTest; tests steam_friends (fake Steam) and pad_naveec0d66
Play it
See the core at work
The core does nothing on its own: grab a game's mod and play it with a friend.