Files
LonaRPG-Online-Games/ModScripts/_Mods/CheatFramework/docs/ModuleGuide.md
T

431 lines
18 KiB
Markdown
Raw Normal View History

2026-10-29 21:59:06 +04:00
# Cheat Framework: Module Guide
This explains how to add a cheat to the Cheat Framework, written for someone who isn't necessarily
comfortable with Ruby or programming yet. It focuses on "what do I write, and what does it do" rather
than how the framework is built internally.
The best example file to read alongside this guide is
[`modules/Pregnancy.rb`](../modules/Pregnancy.rb) — nearly everything below shows up somewhere in it.
A few words you'll see a lot:
- **Module** — one `.rb` file, containing one or more related cheats.
- **`$something`** — a "global variable." Any file can read or change it. Most cheats store their
on/off state or number in one of these.
- **Symbol** (`:toggle`, `:my_key`) — just a label Ruby uses internally. You don't need to understand
why it's written that way, just copy the pattern shown in examples.
- **Monkey-patch** — changing how an existing piece of the game behaves, instead of adding something
new. Covered in §7.
---
## 1. How a module gets loaded
Drop a `.rb` file anywhere under `modules/`. The framework finds it automatically at startup — you
never have to register the file itself anywhere. It reads a small header at the top of your file (see
§2), then runs your file's code once, top to bottom, like any Ruby script.
## 2. Your module's header (optional, but recommended)
```ruby
FrameworkModule = {
name: "Pregnancy", # Just a label, shown in a couple of places
key: :pregnancy, # A short, unique name for your module (no spaces)
menu: :PREGNANCY, # Which menu group your commands land in by default
depends_on: [], # Other modules' :key values that must load before yours (usually empty)
}
```
If you skip this, the framework guesses reasonable defaults from your filename. Fine for a very small
file that only patches existing game behavior and doesn't add its own menu entries.
## 3. Adding a cheat to the menu
Every cheat — a toggle, an editable number, a button — is one `register_command` call:
```ruby
module MenuFramework
module SUBMENU
register_command(
group: :PREGNANCY,
type: :toggle,
key: "Protect Pregnancy",
label: "modules/pregnancy:commands/protect",
state: "$cheat_protect_pregnancy",
gdef: false,
)
end
end
```
- **`group:`** — which existing menu screen this shows up in (`:MISC`, `:TOGGLES`, `:LONA` are common
ones already used elsewhere — reuse one rather than inventing your own unless you're building a
whole new screen, see §4).
- **`type:`** — what kind of row this is. See the table below.
- **`key:`** — a name for this specific command. Must be unique within its `group:`.
- **`label:`** — the text shown to the player. This is a *text key*, not the literal words — see §9.
- **`state:`** — a piece of Ruby, written as **text** (in quotes), that reads the cheat's current value.
Almost always just a `$variable` name.
- **`gdef:`** — the default value, and a signal to the framework "please remember this setting between
play sessions for me." See §5.
## 4. Command types (`type:`)
| type | What it is | You must also provide | Example use |
|---|---|---|---|
| `:toggle` | A simple on/off switch | `state:` | "Infinite Health" |
| `:edit_num` | A number the player can raise/lower | `state:`, `min:`, `max:` | "Max Level" |
| `:edit_list` | Cycles through a fixed set of choices | `state:`, `list:` | "Drop Rate: x1/x2/x4" |
| `:action` | A button that just runs some code once | `action:` | "Heal Fully" |
| `:info` | Read-only text, nothing to press | `state:` | Shows a calculated value |
| `:scene` | Opens a whole new screen | `name:`, `dict:` | See §4a |
### `:toggle` example
```ruby
register_command(
group: :PREGNANCY,
type: :toggle,
key: "Protect Pregnancy",
label: "modules/pregnancy:commands/protect",
state: "$cheat_protect_pregnancy",
gdef: false,
)
```
### `:edit_num` example
```ruby
register_command(
group: :PREGNANCY,
type: :edit_num,
key: "Seedbed",
label: "modules/pregnancy:commands/seedbed",
state: "$game_player.actor.stat['WombSeedBed']",
min: 0,
max: 10,
action: ->(v) { FrameworkUtils.custom_state_edit("WombSeedBed", v) },
)
```
Left/Right in-game raises or lowers the number. `action:` here is a small piece of code that actually
applies the new value `v` to the game — needed because this cheat edits something that's already part
of the save file, not a setting the framework can just remember for you (more on that distinction in §5).
### `:edit_list` example
```ruby
register_command(
group: :PREGNANCY,
type: :edit_list,
key: "Pregnancy Difficulty",
label: "modules/pregnancy:commands/difficulty",
state: "$cheat_pregnancy_difficulty",
gdef: -1,
list: [
{ key: -1, label: "[#{$framework.txt("menu:cheat_toggle/off")}]" },
{ key: 0, label: "[#{$framework.txt("menu:commands/diff_hard")}]" },
{ key: 1, label: "[#{$framework.txt("menu:commands/diff_hell")}]" },
],
)
```
Each entry in `list:` is one choice: `key:` is the actual value stored, `label:` is what's displayed.
Unlike the top-level `label:`, each list entry's `label:` must already be the *finished, translated
text* — call `$framework.txt(...)` yourself, as shown, rather than passing a bare text key.
### `:action` example
```ruby
register_command(
group: :IMPREGNATE,
type: :action,
key: "Clear",
label: "modules/pregnancy:commands/clear",
action: -> { $game_player.actor.cleanup_after_birth },
)
```
Pressing this just runs the code in `action:` once. Nothing to remember, nothing to persist.
### `:info` example
```ruby
register_command(
group: :PREGNANCY,
type: :info,
key: "BabyRace",
label: "modules/pregnancy:info/babyRace",
state: "$game_player.actor.baby_race",
hide: -> { $game_player.actor.preg_level == 0 },
)
```
Just displays whatever `state:` currently is. `hide:` (see §6) is often paired with `:info` rows to
only show them when they're relevant.
## 4a. Adding a whole new screen
If your cheat needs its own dedicated page (like Pregnancy's own menu), register one `:scene` command
that opens into a new group, then register your real commands *into* that group:
```ruby
register_command(
group: :LONA, # the screen this link itself appears on
type: :scene,
key: :pregnancy,
label: "modules/pregnancy:commands/preg",
name: "CheatMenuPregnancy", # the framework builds a screen named after this automatically
dict: :PREGNANCY, # your new group - use this as group: on the commands that belong here
)
```
You don't need to build the screen by hand — the framework generates it the first time it sees that
`name:`. That's enough for the vast majority of cheats. Building a fully custom, hand-drawn screen is
possible but a much bigger topic — look at `Controls.rb` or `InvEdit.rb` for examples if you need it,
or ask someone familiar with the framework for help.
## 4b. Adding your own row to the *Main Menu* (root screen)
§4a's `group:` puts your new screen's link *inside* an existing category, like `:LONA`. If instead you
want your module to show up as its own row on the root screen — the one the player sees when pressing
the Main Menu key, alongside "Miscellaneous," "Toggles," "Character," and "NPC Options" — register with
`MenuFramework::MENU` instead of `MenuFramework::SUBMENU`:
```ruby
module MenuFramework
module MENU
register_command(
type: :scene,
label: "modules/mymodule:commands/root",
name: "CheatMenuMyModule",
order: 40,
)
end
end
```
If your `FrameworkModule` header (§2) already sets `menu:`, that value becomes this new screen's group
automatically — you don't need to pass `dict:` yourself, and any `MenuFramework::SUBMENU.register_command`
calls in the same file don't need `group:` either, for the same reason. `modules/Fixes.rb` is a small,
complete example of this: one `MENU` entry ("Game Fixes") holding several plain `SUBMENU` toggles, none of
which mention `group:` because the header's `menu: :FIXES` already ties them together.
Everything else about the `:scene` command (`type:`, `label:`, `name:`) works exactly like §4a. The only
difference is *where* the link to your new screen appears: `MENU` puts it on the root screen, `SUBMENU`
(with a `group:`) tucks it inside whichever existing category you choose instead.
## 5. Making your cheat remember its setting (`gdef:` + `state:`)
Pass both `gdef:` (a default value) and a `state:` that's a plain `"$variable"` name, and the framework
handles saving/loading for you automatically:
- When the game starts, it reads your cheat's last saved value (or uses your `gdef:` default the very
first time) and puts it into the variable.
- When the player changes it, the framework saves the new value for next time — you don't need to
write any extra code for this, as long as you didn't supply your own `action:`.
**When *not* to use `gdef:`:** if your cheat edits something that's already part of the save file
itself — health, level, an NPC's story flag — don't use `gdef:` at all. That kind of value is already
being saved by the normal game, and needs its own `action:` that actually changes the game object
(see the `:edit_num` example above). `gdef:` is only for a cheat's *own settings*, not for game data
that already exists.
## 6. Showing, hiding, and coloring rows
- **`hide:`** (`true`/`false`, or `-> { }` for a live check) — removes the row from the list entirely.
Use this when a row makes no sense right now (a pregnancy-only field while not pregnant).
- **`enable:`** (default `true`) — keeps the row visible, but grays it out and marks it "Cheat Active"
when `false`. Use this for "this is temporarily blocked by another setting," rather than hiding it.
- **`color:`** — a number that picks a text color, or a `-> { }` that returns one. `16` is commonly
used to highlight "this is the currently active choice"; `8` for a dimmed/informational row.
## 7. Changing how the game itself behaves
Everything so far adds a *new* row to a menu. Sometimes you want to change something the game
*already* does — for example, "block friendly fire" or "let True Deepone talk to NPCs normally."
That's done by replacing one of the game's own methods with your own version, a technique usually
called **monkey-patching**.
The key trick: keep a copy of the original under a new name first, so you can still fall back to it:
```ruby
if $cheat_my_fix >= 0 # only bother at all if the cheat isn't fully disabled
class Game_Actor # reopen whatever class already defines the thing you want to change
alias_method :my_fix_original_heal, :heal_wound # keep a working copy of the original, under a new name
def heal_wound # replace it with your own version
return my_fix_original_heal unless $cheat_my_fix == 1 # only actually change anything if the toggle is on
# ... do your own thing here ...
end
end
end
```
A few things worth understanding line by line:
- `class Game_Actor` doesn't create a new class — since `Game_Actor` already exists in the game, this
*reopens* it, letting you add or replace methods on it. This works for any class in the game.
- `alias_method :new_name, :old_name` copies the method currently called `old_name` and gives that copy
a second name (`new_name`). After this line, both names point at the *same, original* behavior.
- The `def heal_wound` right after it then replaces `heal_wound` with your version. Since you already
saved a copy under a different name, you can still call the original whenever you want (as shown:
falling back to it when the cheat is off).
- Wrapping the whole thing in `if $cheat_my_fix >= 0` means: don't even attempt any of this unless the
cheat has been turned on. If your cheat has ever been fully "Disabled," none of this code runs at
all — which matters if the game ever updates and changes how `heal_wound` works, since your patch
never touching it at all is the safest possible outcome.
- Checking `$cheat_my_fix == 1` *inside* the replaced method (rather than only in the outer `if`) is
what lets the player flip the cheat on and off during play without restarting — see §8.
Always alias to a name that's unique to your cheat (like `my_fix_original_heal`, not just `original`)
so two different modules changing the same method don't collide with each other.
**If you're only adding something new** (a brand-new method the game doesn't already have), you don't
need `alias_method` at all — there's nothing to fall back to. Just reopen the class and write your
method directly, the same way §7's `class Game_Actor` line reopens one.
### 7a. Running code every tick
Some cheats aren't triggered by the player pressing anything — they need to check something
continuously (an aura effect, a passive drain). Reopen `CheatFramework` itself and alias its
`hotkey_trigger` method, which the framework already calls once per frame:
```ruby
class CheatFramework
alias_method :my_fix_hotkey_trigger, :hotkey_trigger
def hotkey_trigger
my_fix_hotkey_trigger
# ... your own per-tick check here ...
end
end
```
Same pattern as §7 — keep a copy of the original under a new name, then call it alongside your own
code, so every other module's tick logic keeps running too.
### 7b. Checking if another mod is enabled
If your patch would conflict with a specific other mod, gate it out when that mod is enabled:
```ruby
if $mod_manager.mods['SomeOtherMod'] && !$mod_manager.mods['SomeOtherMod'].enabled
# ... your patch here ...
end
```
Pair this with `hide: -> { $framework.some_other_mod_enabled? }` (or an equivalent check) on the
`register_command` itself, so the row disappears entirely rather than sitting there doing nothing.
## 8. Restart behavior (`restart:`)
Some cheats can only take effect the moment the game starts (the monkey-patching in §7 can only run
once, when your file first loads) — so if a player turns one on for the first time, nothing will
actually happen until they restart. Left unmarked, that's confusing: the player sees their setting
saved as "On" but nothing changed.
If your cheat has this restart requirement, add `restart:` with the number your `list:` uses to mean
"fully off/disabled" (commonly `-1` or `0` — whatever you picked). For a plain `:toggle` with no such
number, use `restart: true` instead.
```ruby
register_command(
...
state: "$cheat_my_fix",
gdef: -1,
restart: -1, # -1 is this cheat's own "Disabled" value
)
```
With this set, the framework automatically compares "what's picked right now" against "what was
actually running when the game booted," and shows a small `[RESTART]` tag next to the row whenever
they disagree — for example, if the player just flipped it on but hasn't restarted since, or just
flipped it off but the old behavior is technically still active this session. You don't need to write
any of that comparison yourself — just tell it which value means "off."
If your cheat's live behavior is fully controlled by checking `$cheat_my_fix` *inside* the patched
method every time (like the `== 1` check in the §7 example), you generally don't need `restart:` at
all beyond marking the "off" value — the on/off switching itself is already live.
### 8a. Local/Global overrides (`global:`)
This is a separate feature from `gdef:` — it lets the player force a specific value for your cheat
from the Config > Edit Globals screen, independent of what's normally selected. Pass `global: true` or
`global: false` (whichever fits your cheat) to make it eligible:
```ruby
register_command(
...
gdef: false,
global: false, # opts this cheat into the Edit Globals screen
)
```
Most cheats don't need this — it's for settings a player might want to force on/off globally across
every save file regardless of that save's own setting. If you're not sure whether your cheat needs it,
it probably doesn't; just leave `global:` out entirely.
### 8b. Menu order (`order:`)
```ruby
register_command(
...
order: 40,
)
```
A plain number controlling where your row sits in its `group:`, lowest first. Players can also
reorder rows themselves from the in-game Edit Menu Order screen, so treat your number as a starting
default, not a guarantee.
## 9. Hotkeys
```ruby
hotkey: { key: "F4" }
hotkey: { key: "Shift+F4", sound: :sound_WaterSpla }
```
Add this to any command. Players can also assign or change hotkeys themselves from the in-game menu,
so this is just a starting default. `sound:` is optional (a small sound effect on press).
## 10. Text and translations
Any `label:`/`help1:`/`help2:` (and, less commonly, `help3:`/`help4:` for extra help lines) you pass
as a plain string (not starting with `->`) is a *text key*, not the literal words shown to the player.
It points at an entry in a text file:
- `"modules/pregnancy:commands/preg"` → the file `text/ENG/modules/pregnancy.txt`, entry `commands/preg`
- `"menu:commands/misc"` → the file `text/ENG/menu.txt`, entry `commands/misc`
Text files are simple: a key, then the text for it, then a blank line, repeated:
```
commands/preg
Pregnancy
commands/difficulty
Pregnancy Difficulty
```
Add your new keys under `text/ENG/modules/<yourfile>.txt`. That's the one language folder you should
edit yourself — leave the other language folders alone, since those are typically translated
separately by someone else.
## 11. Checklist for a new module
1. Create `modules/YourModule.rb`.
2. Add a `FrameworkModule` header (§2) — optional for something tiny.
3. Decide: are you adding rows to an existing menu, a whole new screen linked from one (§4a), or your
own row on the root Main Menu (§4b)?
4. Register your command(s) using the type table in §4.
5. If it's a cheat *setting* (not existing game data), add `gdef:` + a plain `$variable` `state:` and
skip `action:` — persistence is automatic (§5).
6. If it edits existing game/actor data, write your own `action:` instead.
7. If your cheat changes existing game behavior rather than just adding a menu row, see §7 for how to
do that safely, and §8 if it needs a restart to take effect.
8. Add text keys under `text/ENG/modules/yourmodule.txt` (§10).
9. Test with your cheat both on and off, including turning it on/off without restarting, to make sure
the behavior (and any `[RESTART]` tag) matches what you expect.
10. Optional: set `order:` to control where it sits in the list (§8b), or `global:` if it should
support a forced Local/Global override (§8a). Most cheats need neither.