@@ -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
9279Each 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
247208
248209Place 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) | <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 >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
311220A : 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