From 6509de187791a9b14e5a31f013ae8b9b5cad480d Mon Sep 17 00:00:00 2001 From: IZAO Date: Wed, 3 Dec 2025 12:15:15 +0800 Subject: [PATCH 1/2] Add ClockSetTickRate documentation Updated the documentation for ClockSetTickRate to provide detailed descriptions of its functionality, parameters, and examples. --- .../global-functions/ClockSetTickRate.md | 52 ++++++++++++++++--- 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/docs/01-game-reference/global-functions/ClockSetTickRate.md b/docs/01-game-reference/global-functions/ClockSetTickRate.md index bfa31a4..0fe4871 100644 --- a/docs/01-game-reference/global-functions/ClockSetTickRate.md +++ b/docs/01-game-reference/global-functions/ClockSetTickRate.md @@ -1,5 +1,5 @@ --- -description: ... +description: Controls the speed at which the game clock advances, allowing you to speed up or slow down the passage of time in the game. sidebar_class_name: hidden --- @@ -7,21 +7,59 @@ sidebar_class_name: hidden ## Description -... - +Controls the rate at which the in-game clock advances. This function allows you to speed up or slow down the passage of time in Bully: Scholarship Edition. The default game speed is 1 game minute per 1 real second (60 game minutes per real minute). ```lua -function ClockSetTickRate(param1, ...) --[[ ... ]] end +function ClockSetTickRate(gameMinutesPerRealMinute, unknown) --[[ ... ]] end ``` ## Parameters -... +* `gameMinutesPerRealMinute`: `number` - The number of game minutes that should pass for each real-world minute. Default is 60. + - `60` = Normal speed (1 game minute per real second) + - `120` = 2x speed (2 game minutes per real second) + - `300` = 5x speed (5 game minutes per real second) + - `30` = Half speed (0.5 game minutes per real second) + +* `unknown`: `number` - Purpose unknown. The game scripts use `30` as the standard value. Further testing needed to determine its effect. ## Return Values -... +None. ## Example +```lua +-- Speed up time to 5x normal speed (5 game hours pass per real minute) +function main() + ClockSetTickRate(300, 30) + + while true do + Wait(0) + end +end +``` +```lua +-- Slow down time to half speed +function main() + ClockSetTickRate(30, 30) + + while true do + Wait(0) + end +end +``` +```lua +-- Example from game's decompiled scripts (normal speed) +function F_LoadTime() + ClockSet(8, 0) + WeatherSet(0) + WeatherRelease() + ClockSetTickRate(60, 30) -- Set to normal game speed +end +``` -... +## Notes +- Setting the first parameter to values significantly higher than 60 may cause time to advance too quickly for gameplay. +- Setting it too low (below 10) may cause time to appear frozen or advance extremely slowly. +- The second parameter's purpose is currently undocumented. Standard game scripts consistently use `30`. +- This function can be called at any time during gameplay to dynamically adjust time speed. From 69b1b737dc0ce77942df117e9d2ee4b057794158 Mon Sep 17 00:00:00 2001 From: IZAO Date: Wed, 3 Dec 2025 13:17:27 +0800 Subject: [PATCH 2/2] Revise ClockSetTickRate documentation Updated documentation for ClockSetTickRate function, clarifying parameters, return values, examples, and critical warnings. --- .../global-functions/ClockSetTickRate.md | 117 ++++++++++++++---- 1 file changed, 91 insertions(+), 26 deletions(-) diff --git a/docs/01-game-reference/global-functions/ClockSetTickRate.md b/docs/01-game-reference/global-functions/ClockSetTickRate.md index 0fe4871..77ffaf5 100644 --- a/docs/01-game-reference/global-functions/ClockSetTickRate.md +++ b/docs/01-game-reference/global-functions/ClockSetTickRate.md @@ -2,64 +2,129 @@ description: Controls the speed at which the game clock advances, allowing you to speed up or slow down the passage of time in the game. sidebar_class_name: hidden --- - # ClockSetTickRate - ## Description +Controls the rate at which the in-game clock advances. This function allows you to speed up or slow down the passage of time in Bully: Scholarship Edition. -Controls the rate at which the in-game clock advances. This function allows you to speed up or slow down the passage of time in Bully: Scholarship Edition. The default game speed is 1 game minute per 1 real second (60 game minutes per real minute). +**Important:** This function exhibits non-linear behavior with discrete speed tiers rather than direct multipliers. The relationship between parameters and actual time speed is complex and may not behave as intuitively expected. ```lua -function ClockSetTickRate(gameMinutesPerRealMinute, unknown) --[[ ... ]] end +function ClockSetTickRate(speedParam, requiredParam) --[[ ... ]] end ``` ## Parameters +* `speedParam`: `number` - Speed control parameter (higher values generally = faster time) + - Must be greater than `requiredParam` for reliable behavior + - If equal to or less than `requiredParam`, clock may freeze or behave unpredictably + - See "Tested Speed Values" below for reliable configurations + +* `requiredParam`: `number` - Required parameter with unknown exact purpose + - Game scripts consistently use `30` as the standard value + - Acts as a threshold: `speedParam` should significantly exceed this value + - Setting `speedParam = requiredParam` typically freezes the clock -* `gameMinutesPerRealMinute`: `number` - The number of game minutes that should pass for each real-world minute. Default is 60. - - `60` = Normal speed (1 game minute per real second) - - `120` = 2x speed (2 game minutes per real second) - - `300` = 5x speed (5 game minutes per real second) - - `30` = Half speed (0.5 game minutes per real second) +## Return Values +None. -* `unknown`: `number` - Purpose unknown. The game scripts use `30` as the standard value. Further testing needed to determine its effect. +## Tested Speed Values +Based on systematic testing, these configurations produce reliable results: -## Return Values +| Configuration | Observed Behavior | Notes | +|--------------|-------------------|-------| +| `(60, 30)` | Inconsistent/Frozen | Despite appearing in game scripts, unreliable in testing | +| `(120, 30)` | ~12 game min/real sec | Slower than expected | +| `(300, 30)` | ~36 game min/real sec | Moderate speed | +| `(600, 30)` | ~42 game min/real sec | Fast time progression | +| `(1000, 30)` | ~48 game min/real sec | Very fast time progression | -None. +**Note:** The engine uses discrete speed tiers, not linear scaling. Values between tiers may produce identical speeds. + +## Examples -## Example +### Basic Usage ```lua --- Speed up time to 5x normal speed (5 game hours pass per real minute) +-- Fast time progression (recommended for testing) function main() - ClockSetTickRate(300, 30) + Wait(1000) -- Let game initialize + ClockSetTickRate(600, 30) + print("Time set to fast mode") while true do Wait(0) end end ``` + +### Dynamic Time Control ```lua --- Slow down time to half speed +-- Speed up time during specific hours function main() - ClockSetTickRate(30, 30) - while true do - Wait(0) + local hour = ClockGet() + + if hour >= 23 or hour < 6 then + -- Fast-forward through night + ClockSetTickRate(1000, 30) + else + -- Normal speed during day + ClockSetTickRate(300, 30) + end + + Wait(1000) end end ``` + +### Game Script Example ```lua --- Example from game's decompiled scripts (normal speed) +-- Example from decompiled game scripts (3_B.lua) function F_LoadTime() ClockSet(8, 0) WeatherSet(0) WeatherRelease() - ClockSetTickRate(60, 30) -- Set to normal game speed + ClockSetTickRate(60, 30) end ``` -## Notes +### Alternative Single-Parameter Variant +```lua +-- Found in STimeCycle.lua (behavior untested) +ClockSetTickRate(0.006) +``` + +## Important Notes + +### Critical Warnings +- **First parameter must be significantly larger than second parameter** - Equal or close values cause freezing +- **Non-linear behavior** - Speed increases are not proportional to parameter values +- **Context-dependent** - Function may behave differently during missions vs. free roam +- **Testing environment matters** - Results documented from custom mod scripts, not in-mission behavior + +### Unknowns & Limitations +- Exact purpose of second parameter remains undocumented +- Formula for speed tier calculation is unknown +- Single-parameter variant (0.006) found in game scripts but behavior untested +- Why game's standard (60, 30) appears frozen in testing but works in game scripts + +### Testing Methodology +Results obtained through systematic testing: +1. Set clock to 6:00 AM with `ClockSet(6, 0)` +2. Call `ClockSetTickRate(param1, param2)` +3. Wait exactly 10 real seconds with `Wait(10000)` +4. Measure hours passed with `ClockGet()` + +### Recommendations +- **For modding:** Use tested values (300, 600, 1000) with second parameter = 30 +- **For safety:** Always keep first parameter significantly larger than 30 +- **For debugging:** Use `ClockGet()` and `Wait()` to measure actual time passage +- **Don't assume linear scaling** - Test your specific use case + +## Related Functions +- [`ClockGet()`](ClockGet) - Get current game time +- [`ClockSet()`](ClockSet) - Set game time to specific hour/minute +- [`Wait()`](Wait) - Pause script execution -- Setting the first parameter to values significantly higher than 60 may cause time to advance too quickly for gameplay. -- Setting it too low (below 10) may cause time to appear frozen or advance extremely slowly. -- The second parameter's purpose is currently undocumented. Standard game scripts consistently use `30`. -- This function can be called at any time during gameplay to dynamically adjust time speed. +## Test Environment +- **Game:** Bully: Scholarship Edition (Steam) +- **Tool:** Derpy's Script Loader v11.1 +- **Context:** Custom mod scripts (non-mission) +- **Date:** Systematic testing conducted December 2024