Headless dedicated server for Tiny Block — a living 2D sandbox game built with Godot 4.

Play on Web · Download on the App Store · Get it on Google Play

This repository contains the open-source dedicated server shell. Its world simulation, multiplayer protocol, persistence, and shared presentation code come from the pinned tinyblock-gameplay submodule, which is also used by the official Tiny Block client. Store, advertising, analytics, and other platform integrations remain outside the shared runtime.

Quick start

Prerequisites

• Godot 4.7+ with Linux export templates installed.
• A Tiny Block backend API instance (default: the official public API).

Build

git submodule update --init --recursive

# Export the server binary
godot --headless --export-debug "Dedicated Server (Linux/X11)" build/tinyblock-server.x86_64

Run

./build/tinyblock-server.x86_64 \
  --tinyblock-server \
  --world my_first_world \
  --world-name "My Community Server" \
  --world-mode skyblock \
  --max-players 16

The server:

1. Authenticates as a guest installation.
2. Creates or loads the world identified by --world.
3. Publishes itself in the official server browser.
4. Accepts players using the official Tiny Block client.

Arguments

Argument	Default	Description
--tinyblock-server	—	Required. Enables headless server mode.
--world <id>	world_community_1	Stable world save identifier. Prefix with world_ automatically if omitted.
--world-name <name>	Tiny Block Community	Public display name in the server browser.
--world-mode <mode>	skyblock	One of: skyblock, floating_islands, procedural (Random World), one_block, challenge_run.
--max-players <positive integer>	16	Capacity advertised by this dedicated server. The backend validates and returns this server-defined value to clients.

Supported world modes

• Skyblock — classic skyblock: start on a small island with limited resources.
• Floating Islands — scattered floating islands in the sky.
• Procedural (Random World) — infinite procedurally generated terrain.
• One Block — a single regenerating block; mine it to progress.
• Challenge Run — pre-defined challenge scenarios.

Multiplayer

The server reuses the official Tiny Block backend for:

• Guest authentication.
• Session creation and listing.
• WebSocket signaling.
• WebRTC data channel relay (with automatic fallback).

Active servers appear automatically in the Online Worlds list of the official client at GET /v1/multiplayer/sessions.

Official vs Community

• Official — worlds operated by No Such Games (labelled in the client).
• Community — every other dedicated server.

Your server does not need pre-approval. It appears when its session is active and disappears after the session TTL expires. The server declares its own capacity with --max-players; ordinary player-hosted P2P worlds remain capped at 4.

First-join placement

New players in Procedural, Skyblock, and Floating Islands worlds receive a server-selected safe start instead of always sharing the central spawn. The selector prefers intact walkable natural surface, nearby resources, fewer player-built blocks, and less crowding. It avoids fluids, burning ground, nearby hostile creatures, unsupported fragments, and blocked headroom.

The server remembers first-join allocations in eight-tile buckets and retains that history in the save's community_spawn metadata. Procedural worlds may open at most one nearby unexplored chunk for a newcomer when existing areas are depleted or repeatedly used. Snapshot retries cannot repeatedly generate new chunks. Finite island modes use existing land only; One Block and Challenge keep their canonical starting rules.

Returning players retain their saved positions and inventory. Each selected start also becomes that player's personal respawn checkpoint, stored separately in community_spawn.player_spawns so it survives reconnects and server restarts. If a checkpoint becomes unsafe, the server searches nearby before selecting a replacement. Existing players without a checkpoint receive one at their next death without being moved on login. This does not move the world's shared respawn point or reset terrain. Placement uses the existing authoritative position revision, so compatible clients do not require an update.

Persistence

World saves are stored under the Godot user data directory:

• Linux: ~/.local/share/godot/app_userdata/Tiny Block Server/

Use --world <id> to keep the same world across restarts.

Progression, items, and world state stay on the server. The official Tiny Block servers do not store, back up, or synchronize community world saves.

Pelican and Pterodactyl

Ready-to-import hosting panel profiles are available in pelican-eggs/tiny-block:

• egg-tiny-block-server.json for Pelican Panel.
• egg-pterodactyl-tiny-block-server.json for Pterodactyl Panel.

Both profiles download and verify the selected GitHub release, expose the world mode and player limit as panel variables, and keep saves in persistent server storage.

Project structure

tinyblock-server/
├── project.godot             # Godot project file
├── export_presets.cfg        # Linux dedicated server export
├── scenes/
│   └── server_main.tscn      # Server entry scene
├── gameplay/                 # Pinned shared runtime (Git submodule)
│   ├── scripts/              # Simulation, protocol, rendering, persistence
│   └── assets/               # Shared SFX and emoji artwork
├── scripts/
│   ├── server_main.gd        # Headless server entry point
│   └── analytics.gd          # Stub (no analytics)
├── addons/
│   └── webrtc_native/        # Linux-specific WebRTC native plugin
├── tests/                    # Server and multiplayer tests
├── deploy/
│   ├── run-server.sh         # Example launch script
│   └── tinyblock-server.service.example  # Systemd unit example
├── README.md
├── SELF_HOSTING.md
├── CONTRIBUTING.md
├── SECURITY.md
├── THIRD_PARTY_NOTICES.md
└── LICENSE

License

AGPL-3.0-or-later — see LICENSE.

The Tiny Block name and logos are not granted by the code license. Third-party components retain their original licenses (see THIRD_PARTY_NOTICES.md).