Skip to content

Commit fa691ce

Browse files
author
Lugh (Druid Bot)
committed
docs: Improve ColdStarter documentation per feedback
- Replace packet handler code example with link to actual GitHub file - Remove 'Cost Optimization Tips' section - Remove 'Performance' section - Remove 'Troubleshooting' section - Remove FAQ question about sleeping cost - Simplifies docs to focus on core concepts
1 parent f899f51 commit fa691ce

1 file changed

Lines changed: 5 additions & 101 deletions

File tree

docs/general/coldstarter.md

Lines changed: 5 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -70,24 +70,11 @@ When your server goes idle (no players for X minutes):
7070

7171
### 2. Packet Handler
7272

73-
ColdStarter uses **Lua packet handlers** to understand game-specific connection protocols:
73+
ColdStarter uses **Lua packet handlers** to understand game-specific connection protocols.
7474

75-
```lua
76-
-- Example: Minecraft status packet handler
77-
function handle(ctx, data)
78-
if isStatusRequest(data) then
79-
-- Send fake "server online" response
80-
sendData(generateStatusResponse({
81-
version = "§2▶ Starting...",
82-
players = { online = 0, max = 20 },
83-
description = "Waking up... 30s"
84-
}))
85-
elseif isLoginAttempt(data) then
86-
-- Trigger server wake
87-
finish()
88-
end
89-
end
90-
```
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.
9178

9279
Each game has a custom packet handler:
9380
- **Minecraft**: Responds to status + login packets
@@ -161,32 +148,6 @@ coldstarter:
161148
- **snapshot_mode**: `auto` | `manual` | `none`
162149
- **custom_handler**: Path to custom Lua packet handler
163150

164-
## Cost Optimization Tips
165-
166-
### 1. Enable Snapshots
167-
168-
Faster wake times = better player experience:
169-
```yaml
170-
coldstarter:
171-
snapshot_mode: "auto"
172-
snapshot_schedule: "0 4 * * *" # Daily at 4 AM
173-
```
174-
175-
### 2. Tune Idle Timeout
176-
177-
Balance responsiveness vs cost:
178-
- **5 minutes**: Best for active servers (minimal downtime)
179-
- **15 minutes**: Good default for most hobby servers
180-
- **30 minutes**: Maximum savings for rarely-used servers
181-
182-
### 3. Monitor Usage
183-
184-
Check your actual playtime:
185-
```bash
186-
druid metrics
187-
# Shows: active hours, sleep hours, cost breakdown
188-
```
189-
190151
## Technical Details
191152

192153
### Packet Handler API
@@ -247,58 +208,6 @@ end
247208

248209
Place in `scrolls/<game>/packet_handler/custom_game.lua`
249210

250-
## Performance
251-
252-
### Resource Usage
253-
254-
| State | CPU | RAM | Cost/hour |
255-
|-------|-----|-----|-----------|
256-
| **Active** (playing) | 100% | 2-8GB | $0.014 |
257-
| **Sleeping** (ColdStarter) | &lt;1% | 10-50MB | ~$0 |
258-
| **Waking** (starting up) | 50-100% | 2-8GB | $0.014 |
259-
260-
### Wake Times
261-
262-
| Game | Cold Start | With Snapshot |
263-
|------|-----------|---------------|
264-
| Minecraft (small world) | 30-45s | 10-15s |
265-
| Minecraft (large world) | 60-90s | 20-30s |
266-
| Rust | 40-60s | 15-25s |
267-
| Palworld | 30-50s | 10-20s |
268-
| ARK | 60-120s | 20-40s |
269-
270-
## Troubleshooting
271-
272-
### Server Won't Wake
273-
274-
**Symptoms**: Players connect but server stays asleep
275-
276-
**Solutions**:
277-
1. Check packet handler logs: `druid logs coldstarter`
278-
2. Verify port configuration matches game protocol
279-
3. Test with direct connect (bypass DNS/proxy)
280-
4. Check firewall rules allow incoming traffic
281-
282-
### Slow Wake Times
283-
284-
**Symptoms**: Takes &gt;60s to start
285-
286-
**Solutions**:
287-
1. Enable snapshots for faster restore
288-
2. Reduce world/mod size
289-
3. Check available CPU/RAM resources
290-
4. Consider pre-warming (disable auto-sleep during peak hours)
291-
292-
### "Server Offline" in Browser
293-
294-
**Symptoms**: Server doesn't appear when sleeping
295-
296-
**Solutions**:
297-
1. Verify `sleep_handler` is set in scroll.yaml
298-
2. Check ColdStarter process is running
299-
3. Test packet handler directly
300-
4. Review game-specific protocol requirements
301-
302211
## FAQ
303212

304213
**Q: Can players still see my server when it's asleep?**
@@ -311,9 +220,4 @@ A: ColdStarter queues all connections and wakes the server once. All players con
311220
A: Yes, ColdStarter is transparent to the game server. Mods/plugins work normally.
312221

313222
**Q: Can I disable ColdStarter?**
314-
A: Yes, set `coldstarter.enabled: false` in scroll.yaml or keep the server always-on.
315-
316-
**Q: How much does it cost when sleeping?**
317-
A: Nearly zero (~$0.001/hour for the listener process). The container is fully stopped.
318-
319-
##
223+
A: Yes, set `coldstarter.enabled: false` in scroll.yaml or keep the server always-on.

0 commit comments

Comments
 (0)