Local multiplayer
The local multiplayer sample starts with a two-player join screen, then puts both players in one arena. The top pane follows the cyan player and the bottom pane follows the orange player. Both panes show the same world: head toward the purple cross to meet, or move apart to see each camera follow its own player. If a build fails after you bring some of it into your own game, Read a build error shows how to read the error. To make your own starter game two-player, step by step, see Two players in your game, which ends with this split screen; A camera that follows the player does the camera for one player.
Run it
Section titled “Run it”The sample is in the engine’s folder, not in your game, and your game’s build does not make it.
In the x64 Native Tools Command Prompt, these commands go to
the engine’s folder in a starter project, configure and build there,
run the sample’s tests and start it. From a clone, the first line is cd /d C:\dev\Labrador
instead. Run the samples says how long each step takes, what it prints,
and what each failure means.
cd /d C:\dev\mygame\external\labradorcmake --preset x64-debugcmake --build --preset x64-debug --target LocalMultiplayerSample LocalMultiplayerTestsctest --preset x64-debug -R LocalMultiplayerTests --output-on-failureout\build\x64-debug\samples\local_multiplayer\LocalMultiplayerSample.exeThe ctest line ends 100% tests passed, 0 tests failed out of 1, and the sample’s window opens
on the join screen.
| Source | Join | Menu direction | Select | Leave |
|---|---|---|---|---|
| WASD half | F | W / S | F | G |
| Arrow half | Enter | Up / Down | Enter | Backspace |
| Any of four gamepad slots | Start | Stick or d-pad up / down | A | B |
The first source takes the first free player slot, cyan/top or orange/bottom. A join press cannot also select READY: press Select again. Both players choose READY to start the arena. WASD and arrows then move their assigned players; a bound gamepad uses its left stick. Escape, or B on an assigned gamepad during arena play, exits. No controllers are required. Some keyboards cannot report every combination of simultaneously held keys; use a controller if a combination fails to register. Keys are physical positions, as described in Input.
The build copies all content beside the executable, so it can be launched from any working directory. The default preset needs a Direct3D 11 device; the other rasterising presets use their usual device prerequisites. A null preset records draws without showing a picture.
Give each player their own input
Section titled “Give each player their own input”Player identity belongs to the sample. Its
Lobby maps two player slots
to sources: WASD, arrows, or any of the four pad slots. Simultaneous joins are resolved in that
source order, taking the first free player slot. Each player gets a separate FocusGroup slot
and DirectionRepeat; the menus guide follows that screen.
An observed disconnect in the menu removes only that assignment and its readiness. Reconnect requires a fresh Start press; a connection edge never joins automatically. Leaving also makes that player slot available to another source. These decisions are pure value-based rules in update_lobby and choose_lobby, tested without a controller.
Once both players are ready, the arena keeps those source assignments. Player indices select positions and views; pad slot indices select input and can differ from the player index:
for (int slot = 0; slot < Gamepads::max_count; ++slot){ all_sticks[static_cast<std::size_t>(slot)] = pads.state(slot).left_stick;}directions = read_bound_directions(keyboard, all_sticks, this->sources_);samples/local_multiplayer/play_state.cpp, lines 63–68 at aceb130
The helper reads only the assigned keyboard half or pad stick. Other sources cannot steer that player:
const std::array<InputSource, Arena::player_count>& sources){ const std::array<Vector2F, Arena::player_count> no_sticks = {}; const std::array<Vector2F, Arena::player_count> keys = read_directions(keyboard, no_sticks); std::array<Vector2F, Arena::player_count> directions = {}; for (std::size_t player = 0; player < Arena::player_count; ++player) { const InputSource source = sources[player]; if (key_bindings(source) != nullptr) { directions[player] = keys[source_index(source)]; } else if (const int slot = pad_slot(source); slot >= 0) { sticks[static_cast<std::size_t>(slot)], stick_deadzone); } } return directions;}samples/local_multiplayer/controls.cpp, lines 44–67 at aceb130
Arena::set_directions caps each resulting vector to unit length before movement, so a diagonal
cannot increase movement speed. An absent assigned pad contributes neutral input during play;
the assignment remains attached to that slot. A returning or replacement pad in the slot can
control the player. Slots are observable input positions, not persistent physical identities,
and an undetected replacement between polls cannot be identified. The lobby’s disconnect policy
and the arena’s retained binding are choices in the sample, rather than an engine player manager.
Update one world once
Section titled “Update one world once”The scene owns one Arena, a GameObject that holds both players. It is admitted at startup,
and the state chooses the two-player layout:
this->arena_ = this->scene_->add(std::make_unique<Arena>(this->white_));this->scene_->end_tick();this->rebuild_views();samples/local_multiplayer/play_state.cpp, lines 37–41 at aceb130
Every update supplies the current directions, steps the scene once and then rebuilds its views:
this->arena_->set_directions(directions);this->scene_->update(dt);this->scene_->end_tick();this->rebuild_views();samples/local_multiplayer/play_state.cpp, lines 70–73 at aceb130
The number of views does not change simulation time. Two panes mean two drawings of the same positions. The sample clamps players at the arena boundary; that is movement policy. For contact detection and resolution, continue with Collision.
Follow each player with a camera
Section titled “Follow each player with a camera”ViewportManager’s two_player layout makes top and bottom panes from the current window
size. The sample reserves the 68-pixel HUD strip outside each world view, then clears and
refills the scene’s view list after movement. Each player owns a separate tracking value:
void PlayState::rebuild_views(){ this->scene_->clear_views(); for (size_t player = 0; player < Arena::player_count; ++player) { static_cast<int>(player)); this->panes_[player] = viewport; // Reserve the title strip so a player near the world's top edge is // not covered by the HUD when its camera stops there. const float reserved = std::min(hud_height, std::max(0.0f, viewport.height - 1.0f)); const Viewport world_view(viewport.x, viewport.y + reserved, viewport.width, viewport.height - reserved); const float inset_x = std::min(world_view.width * 0.5f, std::max(minimum_camera_inset, world_view.width * 0.25f)); const float inset_y = std::min(world_view.height * 0.5f, std::max(minimum_camera_inset, world_view.height * 0.25f)); world_view.width - 2.0f * inset_x, world_view.height - 2.0f * inset_y); this->cameras_[player].update(this->arena_->position(player), world_view.size(), dead_zone, this->arena_->bounds()); this->scene_->add_view(world_view, this->cameras_[player].camera()); }}samples/local_multiplayer/play_state.cpp, lines 76–99 at aceb130
FollowCamera is copyable game code in this sample. Its first update starts centred, then
applies the same zone and world constraints as later updates. It pans only enough to bring
a target outside its inclusive dead zone back to the nearest edge.
The sample chooses the central half of the world view, with a minimum 16-pixel inset.
The engine supplies the unit-scale transform; it chooses no following policy:
{ return Camera(this->translation_, 1.0f);}samples/local_multiplayer/follow_camera.cpp, lines 84–87 at aceb130
The viewport’s back-buffer offset is separate. In particular, the bottom player’s camera does not add the bottom pane’s y-offset: the camera maps into world-view-local coordinates, and the viewport places that view below its HUD. World bounds take priority over the dead zone near an edge. An axis smaller than the view is centred rather than given reversed clamp limits:
if (world_size <= size){ next = static_cast<double>(world_start) + (static_cast<double>(world_size) - size) * 0.5;}samples/local_multiplayer/follow_camera.cpp, lines 40–44 at aceb130
For a larger world axis, the first and last possible view positions bound its origin:
const double last = static_cast<double>(world_start) + (static_cast<double>(world_size) - size);next = std::clamp(next, static_cast<double>(world_start), last);samples/local_multiplayer/follow_camera.cpp, lines 47–49 at aceb130
Resizing preserves each old world-space view centre before following and clamping again.
Only update changes the helper; its camera query and all drawing are const. To use it in
your game, copy the header
and source, edit the
source’s first include to the header’s new path and list the .cpp in both game targets.
The copied type is multiplayer::FollowCamera unless you choose another namespace.
A camera that follows the player
explains that optional component after its simpler starter example.
ApplicationOptions::view_capacity is 2, reserving exactly the two recordings the layout needs.
The thread pool ceiling is a separate choice, capped at two workers for this sample:
options.view_capacity = 2;Draw shared state without changing it
Section titled “Draw shared state without changing it”The scene borrows the shell’s thread pool and partitioner, so each view can be recorded on its
own worker. Both workers call Arena::draw on the same object. That method is const; its
temporary drawing values are locals, and positions change only in update.
The HUD runs after the world, on that view’s worker. It selects the player from view_index
and restores the full pane’s viewport and identity camera, keeping text outside the world
view and fixed in its pane:
{ const size_t player = static_cast<size_t>(view_index); const Viewport& world_view = this->scene_->view(view_index).viewport; const float reserved = world_view.y - viewport.y; list.set_viewport(viewport);samples/local_multiplayer/play_state.cpp, lines 103–110 at aceb130
The rest of the callback
draws the player’s controls and a coloured separator. It reads shared state and writes only
its own DrawList. This small scene uses fan-out to demonstrate the contract, rather than as
a performance claim: constructing Scene(nullptr, nullptr) draws the same two views serially.
See Drawing, views and cameras for the rendering model.
Verify the example
Section titled “Verify the example”LocalMultiplayerTests drives the join reducer, source routing, player movement and following
cameras without a window or device. With x64-debug-null, it additionally draws the real arena into the recording
backend and compares serial and parallel output, including both players in both views.
Native null render/audio also runs four real-menu cases using a hidden Application and synthetic
keyboard input: independent focus, held-direction gating, resized recordings and READY-to-arena
transition. Those cases open no graphics/audio API device and poll no physical pad.
For a finite check of the selected renderer and the sample’s actual state:
cd /d C:\dev\mygame\external\labradorstart /wait "" out\build\x64-debug\samples\local_multiplayer\LocalMultiplayerSample.exe --smoke-testecho %errorlevel%From a clone, the first line is cd /d C:\dev\Labrador. The sample is a Windows program, so the
prompt does not wait for it on its own: start /wait makes it wait, and the last line prints 0
when the smoke run passed and another number when it failed.
This bypasses the join screen, renders 120 scripted ticks in a hidden window, checks the two independent final positions
and view count, and exits with a nonzero status on failure. It does not test physical input.
Add --capture out\multiplayer.png to save an early frame on a rasterising backend; the
destination’s parent directory must exist. The sample’s
README describes its scope
and verification in full.
The sample’s tests pass under the native and browser configurations, and its join screen has been looked at on a desktop build and in Chrome. Headless recordings establish routing and geometry; no physical controller has driven the menu.
Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.