18 KiB
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 — nearly everything below shows up somewhere in it.
A few words you'll see a lot:
- Module — one
.rbfile, 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)
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:
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,:LONAare 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 itsgroup:.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$variablename.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
register_command(
group: :PREGNANCY,
type: :toggle,
key: "Protect Pregnancy",
label: "modules/pregnancy:commands/protect",
state: "$cheat_protect_pregnancy",
gdef: false,
)
:edit_num example
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
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
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
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:
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:
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:(defaulttrue) — keeps the row visible, but grays it out and marks it "Cheat Active" whenfalse. 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.16is commonly used to highlight "this is the currently active choice";8for 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:
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_Actordoesn't create a new class — sinceGame_Actoralready 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_namecopies the method currently calledold_nameand gives that copy a second name (new_name). After this line, both names point at the same, original behavior.- The
def heal_woundright after it then replacesheal_woundwith 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 >= 0means: 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 howheal_woundworks, since your patch never touching it at all is the safest possible outcome. - Checking
$cheat_my_fix == 1inside the replaced method (rather than only in the outerif) 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:
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:
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.
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:
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:)
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
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 filetext/ENG/modules/pregnancy.txt, entrycommands/preg"menu:commands/misc"→ the filetext/ENG/menu.txt, entrycommands/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
- Create
modules/YourModule.rb. - Add a
FrameworkModuleheader (§2) — optional for something tiny. - 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)?
- Register your command(s) using the type table in §4.
- If it's a cheat setting (not existing game data), add
gdef:+ a plain$variablestate:and skipaction:— persistence is automatic (§5). - If it edits existing game/actor data, write your own
action:instead. - 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.
- Add text keys under
text/ENG/modules/yourmodule.txt(§10). - 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. - Optional: set
order:to control where it sits in the list (§8b), orglobal:if it should support a forced Local/Global override (§8a). Most cheats need neither.