Split Screen (Local Multiplayer)
Reference for skills/camera-system/SKILL.md — SubViewport-based split-screen with multiple cameras (the example is 2D with Camera2D; a 3D version uses Camera3D in each viewport).
← Back to SKILL.md
7. Split Screen (Local Multiplayer)
Each player gets their own SubViewport with a dedicated Camera2D/Camera3D. A SubViewportContainer renders the viewport into the 2D canvas.
Every Viewport creates its own World2D, so two 2D SubViewports start as two separate worlds: put the level in P1's viewport and give P2 the same world (p2_viewport.world_2d = p1_viewport.world_2d). A 3D SubViewport renders its parent's World3D unless own_world_3d or world_3d is set.
Scene Tree
SplitScreenSetup (Node, the script below)
└── HBoxContainer (fills the screen — use VBoxContainer for a horizontal split)
├── P1Container (SubViewportContainer, player 1 side)
│ └── P1Viewport (SubViewport)
│ └── Player (instantiated by the script: CharacterBody2D with a Camera2D child)
└── P2Container (SubViewportContainer, player 2 side)
└── P2Viewport (SubViewport; world_2d shared with P1Viewport)
└── Player (instantiated by the script: CharacterBody2D with a Camera2D child)GDScript
## SplitScreenSetup.gd — attach to the root node of your split-screen scene
extends Node
@export var player_scene: PackedScene
func _ready() -> void:
# Share P1's World2D so both cameras see the same level and players
$HBoxContainer/P2Container/P2Viewport.world_2d = $HBoxContainer/P1Container/P1Viewport.world_2d
_setup_viewport($HBoxContainer/P1Container/P1Viewport, Vector2i(0, 0))
_setup_viewport($HBoxContainer/P2Container/P2Viewport, Vector2i(1, 0))
func _setup_viewport(viewport: SubViewport, player_index: Vector2i) -> void:
# Match viewport size to half the window
var half_size := Vector2i(
DisplayServer.window_get_size().x / 2,
DisplayServer.window_get_size().y
)
viewport.size = half_size
var player: Node = player_scene.instantiate()
viewport.add_child(player)
# Each player uses a separate input device (gamepad index via player_index.x)
# Wire up device index through an exported property on your player script
if player.has_method("set_device"):
player.set_device(player_index.x)// SplitScreenSetup.cs — attach to the root node of your split-screen scene
using Godot;
public partial class SplitScreenSetup : Node
{
[Export] public PackedScene PlayerScene;
public override void _Ready()
{
// Share P1's World2D so both cameras see the same level and players
GetNode<SubViewport>("HBoxContainer/P2Container/P2Viewport").World2D =
GetNode<SubViewport>("HBoxContainer/P1Container/P1Viewport").World2D;
SetupViewport(GetNode<SubViewport>("HBoxContainer/P1Container/P1Viewport"), new Vector2I(0, 0));
SetupViewport(GetNode<SubViewport>("HBoxContainer/P2Container/P2Viewport"), new Vector2I(1, 0));
}
private void SetupViewport(SubViewport viewport, Vector2I playerIndex)
{
// Match viewport size to half the window
var windowSize = DisplayServer.WindowGetSize();
viewport.Size = new Vector2I(windowSize.X / 2, windowSize.Y);
var player = PlayerScene.Instantiate<Node>();
viewport.AddChild(player);
// Each player uses a separate input device (gamepad index via playerIndex.X)
// Wire up device index through an exported property on your player script
if (player.HasMethod("SetDevice"))
player.Call("SetDevice", playerIndex.X);
}
}Key settings for each SubViewport:
| Property | Value | Reason |
|---|---|---|
world_2d |
P1's world_2d (2D only) |
Each viewport otherwise has its own world |
own_world_3d |
false (default, 3D only) |
true gives the viewport a separate copy of the world |
audio_listener_enable_2d/3d |
true on primary |
Only one viewport drives audio |
transparent_bg |
false |
Avoid alpha blending overhead |
handle_input_locally |
false |
Let the root scene handle input routing |