Skip to content

Commit 86cd9e4

Browse files
olivatoooolivatooo
committed
Added tutorial on fast package reloading to enhance development workflow, including client-server implementation details and customization options.
1 parent c736765 commit 86cd9e4

1 file changed

Lines changed: 224 additions & 0 deletions

File tree

‎docs/getting-started/tutorials-and-examples/fast-package-reloading.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
---
2+
title: Fast Package Reloading
3+
description: >-
4+
Learn how to reload your packages instantly while developing without restarting the server!
5+
tags: [tutorial-example, scripting, development]
6+
---
7+
8+
9+
Speed up your development workflow by reloading packages on-the-fly! This guide shows you how to edit your code and see changes instantly with just one key press.
10+
11+
## Overview
12+
13+
When developing packages, constantly restarting the server to see changes can be time-consuming. With this setup, you can:
14+
15+
1. ✏️ Edit your package files
16+
2. 🎮 Go back to the game
17+
3. ⌨️ Press **P** to reload all packages instantly
18+
4. ✅ See your changes immediately!
19+
20+
## How It Works
21+
22+
This system uses a simple client-server communication:
23+
24+
1. The **client** listens for a key press (P key)
25+
2. When pressed, it sends a remote event to the **server**
26+
3. The **server** receives the event and reloads all running packages
27+
4. All players see a chat notification about which packages are reloading
28+
29+
## Implementation
30+
31+
### Client-Side Code
32+
33+
Add this code to your `Client/Index.lua` file:
34+
35+
```lua title="Client/Index.lua" showLineNumbers
36+
-- Listen for the P key to trigger package reload
37+
Input.Subscribe("KeyDown", function(key_name)
38+
if key_name == "P" then
39+
Console.Log("Reloading Packages")
40+
Events.CallRemote("ReloadPackages")
41+
end
42+
end)
43+
```
44+
45+
### Server-Side Code
46+
47+
Add this code to your `Server/Index.lua` file:
48+
49+
```lua title="Server/Index.lua" showLineNumbers
50+
-- Handle the reload request from clients
51+
Events.SubscribeRemote("ReloadPackages", function()
52+
Console.Log("Reloading Packages")
53+
54+
-- Loop through all loaded packages
55+
for k, v in pairs(Server.GetPackages(true)) do
56+
Console.Log("Reloading Package: " .. v.name)
57+
Chat.BroadcastMessage("Reloading Package: " .. v.name)
58+
59+
-- Reload each package
60+
Server.ReloadPackage(v.name)
61+
end
62+
end)
63+
```
64+
65+
## Usage
66+
67+
Once you've added both code snippets:
68+
69+
1. **Start your server** and connect to it
70+
2. **Edit your package files** (e.g., modify logic in `Server/Index.lua` or `Client/Index.lua`)
71+
3. **Save the changes**
72+
4. **Switch back to the game**
73+
5. **Press the P key**
74+
6. **See your changes take effect immediately!**
75+
76+
You'll see console messages and chat notifications showing which packages are being reloaded.
77+
78+
:::tip Development Workflow
79+
80+
This is especially useful during development phases when you're iterating quickly on features. You can:
81+
82+
- Test small code changes instantly
83+
- Debug issues faster
84+
- Avoid the overhead of restarting the server
85+
- Keep your game state intact while testing
86+
87+
:::
88+
89+
## Customization
90+
91+
### Change the Reload Key
92+
93+
Want to use a different key? Simply change the key name in the client code:
94+
95+
```lua
96+
if key_name == "F5" then -- Changed from "P" to "F5"
97+
-- ...
98+
end
99+
```
100+
101+
Common alternatives:
102+
- `"F5"` - Traditional reload key
103+
- `"R"` - Easy to reach
104+
- `"Insert"` - Less likely to press accidentally
105+
- `"Home"` - Out of the way
106+
107+
### Add Security (Recommended)
108+
109+
By default, any connected player can trigger a reload. For production servers, you should add permission checks:
110+
111+
```lua title="Server/Index.lua" showLineNumbers
112+
-- Only allow admins to reload packages
113+
Events.SubscribeRemote("ReloadPackages", function(player)
114+
-- Check if player is an admin (implement your own logic)
115+
if not IsPlayerAdmin(player) then
116+
Chat.SendMessage("You don't have permission to reload packages!", player)
117+
return
118+
end
119+
120+
Console.Log("Reloading Packages (triggered by: " .. player:GetName() .. ")")
121+
122+
for k, v in pairs(Server.GetPackages(true)) do
123+
Console.Log("Reloading Package: " .. v.name)
124+
Chat.BroadcastMessage("Reloading Package: " .. v.name)
125+
Server.ReloadPackage(v.name)
126+
end
127+
end)
128+
```
129+
130+
### Reload Specific Packages
131+
132+
If you only want to reload certain packages instead of all of them:
133+
134+
```lua title="Server/Index.lua" showLineNumbers
135+
Events.SubscribeRemote("ReloadPackages", function()
136+
-- Only reload specific packages
137+
local packages_to_reload = {"my-package", "another-package"}
138+
139+
for _, package_name in ipairs(packages_to_reload) do
140+
Console.Log("Reloading Package: " .. package_name)
141+
Chat.BroadcastMessage("Reloading Package: " .. package_name)
142+
Server.ReloadPackage(package_name)
143+
end
144+
end)
145+
```
146+
147+
### Add Visual Feedback
148+
149+
Enhance the reload experience with better visual feedback:
150+
151+
```lua title="Client/Index.lua" showLineNumbers
152+
Input.Subscribe("KeyDown", function(key_name)
153+
if key_name == "P" then
154+
Console.Log("🔄 Reloading Packages...")
155+
Events.CallRemote("ReloadPackages")
156+
157+
-- Optional: Show a UI notification
158+
Chat.SendMessage("🔄 Reloading all packages...")
159+
end
160+
end)
161+
```
162+
163+
## Important Notes
164+
165+
:::warning State Preservation
166+
167+
When a package reloads:
168+
- **Global variables** are reset
169+
- **Event subscriptions** are re-registered
170+
- **Spawned entities** may need to be respawned depending on your code
171+
- **Player connections** remain active
172+
173+
Make sure your package initialization code handles reloads gracefully!
174+
175+
:::
176+
177+
:::info Performance
178+
179+
Reloading packages is generally fast, but:
180+
- Complex packages with heavy initialization may take a moment
181+
- All clients will reload the package simultaneously
182+
- Large amounts of spawned entities might cause a brief lag spike
183+
184+
:::
185+
186+
:::caution Production Use
187+
188+
This reload system is primarily intended for **development environments**. For production servers:
189+
190+
1. **Add proper authentication** to prevent unauthorized reloads
191+
2. **Consider disabling** this feature entirely
192+
3. **Use proper release processes** instead of live reloading
193+
4. **Test thoroughly** after any reload before considering changes "live"
194+
195+
:::
196+
197+
## Troubleshooting
198+
199+
### Packages Not Reloading
200+
201+
If pressing P doesn't reload packages:
202+
203+
1. Check the **console** for error messages
204+
2. Verify both client and server code are present
205+
3. Make sure the package name matches exactly
206+
4. Check that `Server.GetPackages(true)` returns your packages
207+
208+
### Changes Not Appearing
209+
210+
If you reload but don't see changes:
211+
212+
1. **Save your files** before reloading
213+
2. Check if your changes have **syntax errors**
214+
3. Look for **errors in the console** after reload
215+
4. Some changes might require **respawning entities**
216+
217+
### Key Press Not Working
218+
219+
If the P key doesn't trigger anything:
220+
221+
1. Check that you're **in-game** (not in console or menu)
222+
2. Verify the **client code** is in the correct file
223+
3. Try a **different key** in case P is bound elsewhere
224+
4. Check console for input subscription errors

0 commit comments

Comments
 (0)