Skip to content

Commit 8a5f29c

Browse files
author
Lugh (Druid Bot)
committed
docs: Cut ColdStarter by 50% - keep only essentials
1 parent 9a148fe commit 8a5f29c

1 file changed

Lines changed: 47 additions & 176 deletions

File tree

‎docs/cli/coldstarter.md‎

Lines changed: 47 additions & 176 deletions
Original file line numberDiff line numberDiff line change
@@ -1,223 +1,94 @@
11
---
22
sidebar_position: 2
3-
title: ColdStarter System
4-
description: Understand how Druid's ColdStarter system enables wake-on-demand automation and 70-90% cost savings
3+
title: ColdStarter
4+
description: Wake-on-demand system for cost savings
55
---
66

7-
# ColdStarter System
7+
# ColdStarter
88

9-
ColdStarter is Druid's intelligent wake-on-demand system that automatically starts your game server when players connect, while keeping costs near zero when idle. It's the core technology that makes Druid cost-effective for hobby servers.
10-
11-
## What is ColdStarter?
12-
13-
ColdStarter acts as a lightweight listener proxy that intercepts incoming connections to your game server. When a player tries to connect:
14-
15-
1. **Sleeping**: Server is powered down, consuming minimal resources (~0 cost)
16-
2. **Wake signal**: Player connects, ColdStarter intercepts the connection
17-
3. **Starting**: ColdStarter wakes the server in the background
18-
4. **Ready**: Player is connected to the now-running server
19-
20-
The magic? **Your server still appears "online" in server browsers even when sleeping.**
21-
22-
## Key Benefits
23-
24-
### 💰 **70-90% Cost Savings**
25-
26-
Pay only for active playtime, not idle time. A typical hobby server might run:
27-
- **Traditional hosting**: 24/7 = 720 hours/month
28-
- **With ColdStarter**: 50-150 hours/month actual playtime
29-
30-
**Example cost breakdown:**
31-
```
32-
Traditional: $10/month × 720 hours = $10
33-
Druid: $0.014/hour × 100 hours = $1.40/month
34-
35-
Savings: 86%
36-
```
37-
38-
### ⚡ **Seamless User Experience**
39-
40-
- Server shows as "online" in Minecraft/Rust/etc. server browsers
41-
- Players connect normally (10-30 second wake time)
42-
- Status messages show "Starting..." or "Waking up..."
43-
- No configuration needed by players
44-
45-
### 🌍 **Always Available**
46-
47-
Your server is accessible 24/7, but only costs money when actually in use. Perfect for:
48-
- Hobby servers with irregular play schedules
49-
- Friend groups in different time zones
50-
- Testing and development environments
51-
- Event-based servers
9+
ColdStarter automatically wakes your server when players connect, then puts it to sleep when idle. You only pay for active time.
5210

5311
## How It Works
5412

55-
### Architecture
56-
57-
```
58-
Player → ColdStarter Listener → [Wake] → Game Server
59-
↓
60-
Lua Packet Handler
61-
(Server status response)
62-
```
63-
64-
### 1. Listener Proxy
65-
66-
When your server goes idle (no players for X minutes):
67-
- Main game server shuts down
68-
- Lightweight ColdStarter listener starts on the same port
69-
- Memory footprint: ~10-50MB (vs 2-8GB for game server)
70-
71-
### 2. Packet Handler
72-
73-
ColdStarter uses **Lua packet handlers** to understand game-specific connection protocols.
74-
75-
**Example**: [Minecraft packet handler (minecraft.lua)](https://github.com/highcard-dev/scrolls/blob/main/scrolls/minecraft/papermc/1.21.7/packet_handler/minecraft.lua)
76-
77-
The handler intercepts incoming packets, responds with server status, and triggers wake when players connect.
78-
79-
Each game has a custom packet handler:
80-
- **Minecraft**: Responds to status + login packets
81-
- **Rust**: Responds to query protocol
82-
- **Source games**: Responds to A2S_INFO queries
83-
- **Hytale**: Protocol TBD (ready for launch)
13+
1. **Idle**: No players → server sleeps (minimal cost)
14+
2. **Connect**: Player tries to join → ColdStarter intercepts
15+
3. **Wake**: Server starts in background (10-30 seconds)
16+
4. **Play**: Player connects to running server
8417

85-
### 3. Wake Process
18+
Your server still shows as "online" in server browsers while sleeping.
8619

87-
When a player attempts to connect:
20+
## Cost Savings
8821

89-
1. **Intercept**: ColdStarter receives connection
90-
2. **Respond**: Send "Starting..." status to player
91-
3. **Wake**: Restore server container from snapshot
92-
4. **Handoff**: Transfer connection to real server
93-
5. **Cleanup**: ColdStarter listener shuts down
22+
Typical hobby server:
23+
- **Without ColdStarter**: 720 hours/month (24/7)
24+
- **With ColdStarter**: 100 hours/month (actual playtime)
9425

95-
Typical wake time: **10-30 seconds** (varies by game/world size)
96-
97-
### 4. Server Browser Integration
98-
99-
The clever part: **Server browsers never know the server is asleep.**
100-
101-
- **Minecraft**: Shows in server list with "🕐 Waiting..." status
102-
- **Rust**: Appears in Rust+ app and server browser
103-
- **Steam games**: Shows in Steam server browser
104-
- **Direct connect**: Works normally with IP:PORT
105-
106-
## Supported Games
107-
108-
ColdStarter has optimized handlers for:
109-
110-
| Game | Status | Protocol Handler |
111-
|------|--------|------------------|
112-
| Minecraft (all variants) | ✅ Stable | `minecraft.lua` |
113-
| Rust | ✅ Stable | `rust.lua` |
114-
| Hytale | ✅ Ready | `hytale.lua` |
115-
| ARK: Survival | ✅ Stable | LGSM generic |
116-
| Palworld | ✅ Stable | LGSM generic |
117-
| Valheim | ✅ Stable | LGSM generic |
118-
| 7 Days to Die | ✅ Stable | LGSM generic |
119-
| Other LGSM games | ✅ Stable | Generic handler |
120-
121-
**Total**: 95 published scrolls with ColdStarter support
26+
**Result**: ~85% cost reduction
12227

12328
## Configuration
12429

125-
ColdStarter is configured automatically per-scroll. Key settings:
126-
127-
### Scroll Configuration
30+
Configured per-scroll via `scroll.yaml`:
12831

12932
```yaml
130-
# scroll.yaml
13133
ports:
13234
- name: game
13335
port: 25565
13436
protocol: tcp
135-
sleep_handler: "minecraft.lua" # Packet handler
136-
check_activity: true # Monitor for idle
137-
138-
coldstarter:
139-
idle_timeout: 300 # Shutdown after 5min idle
140-
wake_timeout: 60 # Max wake time
141-
snapshot_mode: "auto" # Enable snapshots
37+
sleep_handler: packet_handler/minecraft.lua
38+
start_delay: 10
39+
check_activity: true
14240
```
14341
144-
### Advanced Options
42+
### Port Options
14543
146-
- **idle_timeout**: How long to wait before sleeping (seconds)
147-
- **wake_timeout**: Max time allowed for wake (kills if exceeded)
148-
- **snapshot_mode**: `auto` | `manual` | `none`
149-
- **custom_handler**: Path to custom Lua packet handler
44+
- `sleep_handler` - Path to Lua packet handler (required for ColdStarter)
45+
- `start_delay` - Seconds to wait before port is ready
46+
- `check_activity` - Enable idle detection
47+
- `finish_after_command` - Wait for command to finish before opening port
15048

151-
## Technical Details
49+
## Packet Handlers
15250

153-
### Packet Handler API
51+
Lua handlers respond to game protocols while server is asleep.
15452

155-
Lua handlers have access to:
53+
**Example:** [minecraft.lua](https://github.com/highcard-dev/scrolls/blob/main/scrolls/minecraft/papermc/1.21.7/packet_handler/minecraft.lua)
54+
55+
### Lua API
15656

15757
```lua
158-
-- Send data back to client
58+
-- Send data to client
15959
sendData(string)
16060
161-
-- Close connection
162-
close(data)
163-
164-
-- Trigger server wake + handoff
61+
-- Trigger server wake
16562
finish()
16663
167-
-- Get queue status (install/restore)
64+
-- Get snapshot/queue status
16865
get_queue()
169-
170-
-- Get snapshot progress
171-
get_snapshot_mode()
17266
get_snapshot_percentage()
173-
174-
-- Time since wake started
17567
get_finish_sec()
176-
177-
-- Debug logging
178-
debug_print(string)
17968
```
18069

181-
### Custom Handlers
70+
## Supported Games
71+
72+
All 95 published scrolls support ColdStarter:
73+
- Minecraft (all variants)
74+
- Rust (Vanilla, Oxide)
75+
- Hytale
76+
- 10 LGSM games (Palworld, ARK, CS2, etc.)
77+
78+
## Custom Handlers
18279

183-
Create your own for unsupported games:
80+
Create `packet_handler/game.lua` in your scroll:
18481

18582
```lua
186-
-- custom_game.lua
18783
function handle(ctx, data)
188-
-- 1. Parse incoming packet
189-
local packet_type = parsePacket(data)
190-
191-
-- 2. Handle status requests
192-
if packet_type == "STATUS" then
193-
sendData(buildStatusResponse({
194-
name = "My Server",
195-
players = 0,
196-
max_players = 20,
197-
status = "Waking up..."
198-
}))
84+
-- Parse packet
85+
if isStatusRequest(data) then
86+
sendData("Server starting...")
19987
end
20088
201-
-- 3. Handle connection attempts
202-
if packet_type == "CONNECT" then
203-
sendData("Please wait, server starting...")
204-
finish() -- Wake the server
89+
-- Wake on connect
90+
if isConnectionAttempt(data) then
91+
finish()
20592
end
20693
end
20794
```
208-
209-
Place in `scrolls/<game>/packet_handler/custom_game.lua`
210-
211-
## FAQ
212-
213-
**Q: Can players still see my server when it's asleep?**
214-
A: Yes! ColdStarter responds to status queries, so your server appears "online" with a "Starting..." message.
215-
216-
**Q: What happens if multiple players connect at once?**
217-
A: ColdStarter queues all connections and wakes the server once. All players connect when ready.
218-
219-
**Q: Does this work with mods/plugins?**
220-
A: Yes, ColdStarter is transparent to the game server. Mods/plugins work normally.
221-
222-
**Q: Can I disable ColdStarter?**
223-
A: Yes, set `coldstarter.enabled: false` in scroll.yaml or keep the server always-on.

0 commit comments

Comments
 (0)