Skip to content

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.

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.

Terminal window
cd /d C:\dev\mygame\external\labrador
cmake --preset x64-debug
cmake --build --preset x64-debug --target LocalMultiplayerSample LocalMultiplayerTests
ctest --preset x64-debug -R LocalMultiplayerTests --output-on-failure
out\build\x64-debug\samples\local_multiplayer\LocalMultiplayerSample.exe

The 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.

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:

samples/local_multiplayer/play_state.cpp
std::array<Vector2F, Gamepads::max_count> all_sticks;
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_);

The helper reads only the assigned keyboard half or pad stick. Other sources cannot steer that player:

samples/local_multiplayer/controls.cpp
std::array<Vector2F, Arena::player_count> read_bound_directions(
const Keyboard& keyboard,
const std::array<Vector2F, Gamepads::max_count>& sticks,
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 (source == InputSource::keyboard_left)
{
directions[player] = keys[0];
}
else if (source == InputSource::keyboard_right)
{
directions[player] = keys[1];
}
else if (const int slot = pad_slot(source); slot >= 0)
{
directions[player] = apply_deadzone(
sticks[static_cast<std::size_t>(slot)], 0.2f);
}
}
return directions;
}

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.

The scene owns one Arena, a GameObject that holds both players. It is admitted at startup, and the state chooses the two-player layout:

samples/local_multiplayer/play_state.cpp
this->scene_ = std::make_unique<Scene>(this->app_->thread_pool(), this->app_->partitioner());
this->arena_ = this->scene_->add(std::make_unique<Arena>(this->white_));
this->scene_->end_tick();
this->app_->viewport_manager()->set_layout(ScreenLayout::two_player);
this->rebuild_views();

Every update supplies the current directions, steps the scene once and then rebuilds its views:

samples/local_multiplayer/play_state.cpp
this->arena_->set_directions(directions);
this->scene_->update(dt);
this->scene_->end_tick();
this->rebuild_views();

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.

ViewportManager’s two_player layout makes top and bottom panes from the current window size. The sample clears and refills the scene’s view list after movement, so cameras track the new positions and the layout follows window resizing:

samples/local_multiplayer/play_state.cpp
void PlayState::rebuild_views()
{
this->scene_->clear_views();
for (size_t player = 0; player < Arena::player_count; ++player)
{
const Viewport viewport = this->app_->viewport_manager()->player_viewport(
static_cast<int>(player));
this->scene_->add_view(viewport, this->arena_->camera(player, viewport));
}
}

The camera’s translation is the player’s world position minus half the pane size. At scale 1, this puts the player at the pane centre:

samples/local_multiplayer/arena.cpp
Camera Arena::camera(size_t player, const Viewport& viewport) const
{
return Camera(this->position(player) - viewport.size() * 0.5f, 1.0f);
}

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 pane coordinates, and the viewport places that pane on the buffer. Near an arena edge the camera shows the empty space beyond it; A camera that follows the player stops a camera at the world’s edge.

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:

samples/local_multiplayer/main.cpp
options.view_capacity = 2;
options.max_threads = std::min(2, default_thread_count());

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 switches the list to the identity camera, keeping text fixed in its pane while the world moves beneath it:

samples/local_multiplayer/play_state.cpp
this->scene_->draw(renderer, [this](int view_index, DrawList& list)
{
const size_t player = static_cast<size_t>(view_index);
const Viewport& viewport = this->scene_->view(view_index).viewport;
list.set_camera(Camera::default_camera);

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.

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:

Terminal window
cd /d C:\dev\mygame\external\labrador
start /wait "" out\build\x64-debug\samples\local_multiplayer\LocalMultiplayerSample.exe --smoke-test
echo %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.

Documentation for Labrador v0.3.0. Built from Labrador 0f4f503 of 2026-11-03.

All documentation versions