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 (key_bindings(source) != nullptr)
{
directions[player] = keys[source_index(source)];
}
else if (const int slot = pad_slot(source); slot >= 0)
{
directions[player] = apply_deadzone(
sticks[static_cast<std::size_t>(slot)], stick_deadzone);
}
}
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 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:

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->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));
const RectangleF dead_zone(inset_x, inset_y,
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());
}
}

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:

samples/local_multiplayer/follow_camera.cpp
Camera FollowCamera::camera() const
{
return Camera(this->translation_, 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 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:

samples/local_multiplayer/follow_camera.cpp
if (world_size <= size)
{
next = static_cast<double>(world_start) +
(static_cast<double>(world_size) - size) * 0.5;
}

For a larger world axis, the first and last possible view positions bound its origin:

samples/local_multiplayer/follow_camera.cpp
const double last = static_cast<double>(world_start) +
(static_cast<double>(world_size) - size);
next = std::clamp(next, static_cast<double>(world_start), last);

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:

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 restores the full pane’s viewport and identity camera, keeping text outside the world view and fixed in its pane:

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->panes_[player];
const Viewport& world_view = this->scene_->view(view_index).viewport;
const float reserved = world_view.y - viewport.y;
list.set_viewport(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.

Development documentation (unreleased). Built from Labrador aceb130 of 2026-11-20.

All documentation versions