name: hgame-gms2-safe-edit description: Safe editing guidance for the hgame GameMaker Studio 2 JRPG project. Use when Codex or an agent needs to inspect, modify, refactor narrowly, debug, or extend this repository's GML code, GMS2 objects, rooms, scripts, save data, inventory, equipment, character, skill, menu, NPC, movement, audio, or room-state systems.

HGame GMS2 Safe Edit

First Steps

Use this skill before changing this repository. Treat the project as a GMS2 2024.13.1+ project with hand-maintained GML conventions and fragile serialized data.

1. Inspect the local files before editing. Start with rg --files, then use targeted rg searches for function names, enum names, global. variables, and ds_grid_* access.
2. Prefer editing .gml script/event files. Avoid .yy edits unless resource metadata truly must change, such as adding/removing an event in eventList, changing an object parent/child relationship, or adding/removing a GMS2 resource.
3. Before using any GML API, verify that it already appears in the project or is a current built-in GameMaker function. Do not invent helper names or use plugin-only/deprecated APIs.
4. Keep changes narrow. Do not reorganize the project, rename resources, or redesign the save/inventory/equipment/character data model unless the user explicitly asks for that refactor.
5. Preserve existing ds_grid, struct, enum, sentinel, and save-file contracts. These are part of runtime behavior, not incidental implementation details.
6. When editing GML, prefer APIs already present in this repository. If a new GameMaker API is needed, verify it against current official GameMaker documentation before using it.

Project Map

• hgame.yyp and hgame.resource_order: GMS2 project metadata. Avoid manual edits unless a resource change requires it.
• scripts/: reusable GML functions and data catalogs. This is the safest place for most logic changes.
• objects/: object event code. Event files are named by GMS2 event type, such as Create_0.gml, Step_0.gml, Draw_64.gml, and Destroy_0.gml.
• rooms/: room metadata and instance creation code. Instance creation files often set global.bgm, global.roomid, item/NPC state, or room transitions.
• sprites/, sounds/, fonts/, tilesets/, options/: resource metadata and assets. Treat .yy files here as generated/editor-owned unless a resource task requires touching them.
• notes/: developer notes, not runtime code.

Core Systems

Boot, Globals, Time, Debug

• objects/obj_title_menu/* initializes title-menu state, audio volume globals, settings, global.savef, global.sub_menu, global.talking, and global.noresting.
• objects/obj_gamestart/Create_0.gml initializes a new or loaded run: debug flag, message speed, total/game time, global.talking, global.overweight, global.noresting, global.bgm, global.battle, global.gameover, room status, and global.saveDATA.
• objects/obj_gamestart/Step_0.gml creates or re-creates persistent runtime managers and player/partner instances.
• objects/obj_control/* defines global input aliases via globalvar: lkey, rkey, ukey, dkey, akey, bkey, xkey, ykey, pressed/released variants, function keys, and key_cooldown.
• objects/obj_allways/* manages debug hotkeys, quick save/load, total/game time, in-game time, mp_grid pathfinding grids, battle BGM gain, and game-over transitions.
• objects/obj_bgm/* manages BGM start/loop tracks and fades by global.bgm; global.battle controls the second BGM group in obj_allways.

Save And Load

• scripts/scr_saving_system/scr_saving_system.gml is the central save/load script. Be very conservative here.
• scr_saving(_datanum) writes savedataN.sav as JSON through buffer_create, buffer_write, and buffer_save.
• Inventory and equipment are serialized with ds_grid_write; their heights are stored separately.
• Room status is stored as a versioned struct returned by room_status_save_data(). The active room-state format starts at version = 2; legacy grid migration code was intentionally removed because the project had no meaningful old room-state saves yet. Future migrations should be added through room_status_load_data() version dispatch.
• Character data is not saved as raw nested grids. It clones each character struct with variable_clone, converts skill_list and spellbook_list grids into arrays of structs, and writes global.saveDATA.Schara_status.
• scr_loading(_datanum) only parses JSON into global.saveDATA. Rehydration happens later in object code:
  • obj_gamestart/Create_0.gml restores global time and merges saved room state over fresh reroomsatus() defaults.
  • obj_item_manager/Step_0.gml rebuilds inventory and equipment from ds_grid_read.
  • obj_charsatus/Step_0.gml rebuilds character structs, skill_list, and spellbook_list grids.
• Do not change save field names, grid widths, enum columns, or character struct fields without a migration plan and backwards compatibility.

Character Data

• scripts/scr_character/scr_character.gml replaces the older deprecated dis_scr_gamerule character implementation.
• chara_id(_id) returns a character struct. Important fields include identity, stats, modifiers, HP/MP, class/race strings, equipment slots, skill_list, spellbook, and spellbook_list.
• obj_charsatus/Create_0.gml creates global chara_status with width chara_status_w = 2; column 0 is character id, column 1 is the character struct.
• load_chara(_id) searches chara_status, returns the stored struct, applies old-save compatibility for spellbooks, clamps HP/MP, and refreshes modifiers.
• Character equipment slots store full equipment structs or 0: main_h, sec_h, armor, accessoryA, accessoryB, accessoryC.

Inventory And Equipment

• scripts/scr_item/scr_item.gml defines enum DS_INVENTORY: NAME = 0, AMOUNT = 1, I_ID = 2.
• obj_item_manager/Create_0.gml creates global inventory with inventory_w = 3 and global equipment with equipment_w = 4.
• item_id(_id) is the item catalog and returns a struct. Some item ids are decimals, such as 0.1, 1.1, and 2.8; preserve that convention.
• add_item_id() merges stacks by item id and caps inventory amounts at 999; empty first cell value 0 means an empty grid row.
• scripts/scr_equipment/scr_equipment.gml defines enum DS_EQUIPMENT: NAME = 0, AMOUNT = 1, E_ID = 2, CUR_DURABILITY = 3.
• equipment_id(_id) is the equipment catalog. equip_parts values are meaningful: 0 two-handed main-hand only, 1 main hand only, 2 main or off hand, 3 armor, 4 accessory slots.
• apply_equipment() removes old attr mods/effects, sets a slot, applies new attr mods/effects, then calls recalc_AC().
• Equipment/item effect lists use arrays of structs like {type: APP_EFFECT.ITEM_POTION, t_id:[2,4,2]}. Route new effects through the existing APP_EFFECT enum and apply_effect() pattern.

Skill And Spell Data

• scripts/scr_skill/scr_skill.gml defines DS_SKILL and DS_SPELL.
• DS_SKILL columns are NAME, S_ID, and SOURCE_COUNT. SOURCE_COUNT allows multiple sources for the same skill; remove_skill_id() decrements before removing rows.
• DS_SPELL columns are NAME, S_ID, and ISENALBE = 2; ISENABLE = 2 is an alias. Preserve the existing misspelled ISENALBE uses for compatibility.
• add_spell_id() may also add a skill when a spell is enabled. set_spell_enable_by_row() enforces get_spell_enable_limit().

Room State And Instance Data

• scripts/scr_roomsatus/scr_roomsatus.gml creates global room_status as a versioned struct: { version, rooms }.
• Each room entry stores room_id, room_name, room_data, and an instances array. Room-level state should use room_status_current_set_room_custom() / room_status_current_get_room_custom().
• Each tracked instance uses a stable rs_id string rather than a grid column. Current tracked types are "item", "equipment", "npc", and "hostile_npc".
• Room instance Creation Code should set rs_id = "<stable instance id>" for tracked placed instances. Item and equipment instances can also set rs_restorable.
• obj_item_p, obj_equip_p, obj_npc, and obj_hostile_npc initialize rs_id, rs_restorable, and rs_state_ready, then apply/capture room state through the room_status_* helpers during Step/interaction.
• obj_hostile_npc instances without Creation Code can be auto-bound by type and default position when they have a matching registry entry.
• restor_roomsatus() remains as a compatibility wrapper for rest/refresh flows, but it now restores entries from the struct registry instead of the old grid.
• NPC positions are captured continuously, but default room entry behavior does not restore saved positions unless restore_position is set, for example via room_status_current_set_restore_position().
• For complex NPC or room-specific flags, prefer the generic custom helpers over adding one-off grid columns or hard-coded save fields.

Menus, Messages, And Interaction

• Menu objects use global.pause and global.sub_menu as state-machine controls. Destroy events usually reset global.sub_menu = 0.
• Menu navigation uses input aliases from obj_control and helper scr_menu_movement_jump().
• scripts/scr_msg/scr_msg.gml creates pages/options and obj_msgbox; scripts/scr_msg_game/scr_msg_game.gml contains message ids and branching text.
• Item use creates obj_menu_useitem and stores a closure in u_scr, then applies the underlying effect after a target character is chosen.

Movement And NPCs

• scripts/scr_movement/scr_movement.gml applies velocity, facing, vector path movement, and solid collision nudging. It expects instance fields like vx, vy, vs, acc, sprinting, face, and block_solid.
• scripts/scr_player_movement/scr_player_movement.gml translates global input aliases into player velocity and sprint state.
• scripts/scr_npc_behavior/scr_npc_behavior.gml dispatches numeric NPC behaviors: idle/default, random move, talking, follow, close follow, and away.
• NPC objects initialize movement fields and block_solid in their Create events. Hostile NPCs also maintain path state with follow_path, follow_target, and follow_timer.

GML Style

• Use GMS2.3+ script functions: function name(_arg) { ... }.
• Prefix function parameters and temporary locals with _ where the surrounding code does so, such as _id, _chara, _equipment, _row.
• Keep catalog functions as switch(_id) blocks returning structs. Add new item/equipment/skill cases near similar ids and keep #region comments when helpful.
• Use argument_count and argument[] for optional arguments when matching existing scripts.
• Use existing input aliases (akey, bkey, dpkey, etc.) instead of calling raw keyboard/gamepad checks from unrelated code.
• Use global. for project-level state where the project already does; use globalvar only for the established shared grids/input variables.
• Use 0 as the existing empty sentinel in ds_grid rows and equipment slots; use undefined or noone only where existing code expects them.
• Keep Chinese in-game text and comments consistent with nearby files. Do not rewrite wording unless the task is text/content work.
• Preserve existing formatting in touched files. This codebase uses mixed semicolon style and GML brace conventions; do not run broad formatters.

Reserved Instance Variables

GameMaker Studio 2 uses many built-in instance variables that must NOT be used as local or temporary variable names.

Examples include but are not limited to:

• x, y
• hspeed, vspeed, speed, direction
• image_index, image_speed
• visible, solid
• id, object_index

Rules:

• NEVER use built-in instance variable names as local variables.
• ALWAYS use _ prefix for parameters and temporary variables (e.g. _x, _y, _speed).
• If a variable name conflicts with a built-in variable, rename it safely.
• Treat x and y as position properties only, never as generic variables.

If a variable name could potentially conflict with a built-in variable, prefer:

• _name for parameters and locals
• tmp_name for temporary values

Forbidden Changes

• Do not manually churn .yy files, hgame.yyp, or hgame.resource_order for normal logic edits.
• Do not invent GML functions, resource names, audio groups, sprites, object names, or scripts. Verify first with rg or official GameMaker docs.
• Do not use plugin-only APIs or deprecated APIs. Deprecated files here, such as dis_scr_gamerule and dis_scr_item_script_execute, are reference/legacy material, not patterns to revive.
• Do not broadly refactor the save system, inventory/equipment grids, character structs, room_status, or menu state machines without explicit user approval.
• Do not break these enum/grid contracts:
  • DS_INVENTORY: NAME, AMOUNT, I_ID
  • DS_EQUIPMENT: NAME, AMOUNT, E_ID, CUR_DURABILITY
  • DS_SKILL: NAME, S_ID, SOURCE_COUNT
  • DS_SPELL: NAME, S_ID, ISENALBE/ISENABLE
• Do not remove old-save compatibility checks from load_chara() or obj_charsatus/Step_0.gml.
• Do not change save JSON field names or grid widths unless also handling migration.

Staged Resource Creation

When a new GMS2 script/object/resource is needed, do not directly register it as a real project resource unless explicitly approved.

Preferred workflow:

1. Create staged files using the prefix NEW_.

   • Example: NEW_scr_potion_system.gml
   • Example: NEW_obj_potion_menu_Create_0.gml
   • Example: NEW_obj_potion_menu_Step_0.gml

2. Do not modify:

   • hgame.yyp
   • hgame.resource_order
   • resource tree metadata

3. Tell the user what to create manually in GameMaker IDE.

   • Example: create a script named scr_potion_system
   • Example: create an object named obj_potion_menu
   • Example: add Create / Step / Draw GUI events as needed

4. After the user creates the resource in GameMaker IDE, move/copy the staged NEW_ code into the corresponding .gml event/script file, or let the user do it own.

5. Remove the NEW_ prefix only after the IDE-created resource exists.

6. Never treat NEW_ files as runtime code. They are drafts/templates only.

Encoding

All project text files are UTF-8 encoded.

Rules:

• Always read and write text files as UTF-8.
• Preserve Chinese comments, strings, dialogue, and UI text.
• If Chinese text appears garbled, assume the file was read with the wrong encoding and re-read it as UTF-8.
• Do not rewrite, normalize, or “repair” garbled text unless the user explicitly asks.
• Do not change line endings or file encoding during unrelated edits.

Safe Edit Checklist

Before editing:

1. Identify the owning system and read its script plus the relevant object events.
2. Search every function/enum/global/grid column you plan to touch.
3. Check whether the target file participates in save/load or room instance creation.
4. If a .yy edit seems necessary, explain why and limit the diff to the exact metadata field.

While editing:

1. Prefer adding a small function, enum case, catalog case, or localized branch over changing shared flow.
2. Keep data shape stable. Extend structs additively and add fallback checks for old saves.
3. Use existing helpers: load_chara, load_inventory, load_equipment, add_item_id, add_equipment_id, apply_effect_list, create_msg_box, scr_menu_movement_jump.
4. Keep room state ids, item/equipment ids, and skill ids deterministic and documented near their cases.

After editing:

1. Run rg -n checks for typos in changed function, enum, and field names.
2. Review git diff and confirm no unintended .yy, asset, or generated metadata churn.
3. For save-related changes, reason through new game, old save load, save, reload, and empty-grid cases.
4. If GameMaker is not available for a full compile, state that limitation clearly in the final response.

Skill Maintenance

This skill may be updated when the project architecture changes.

Rules:

• Do not weaken or remove safety rules without explicit user approval.
• Prefer appending new project facts over rewriting old sections.
• When code and this skill disagree, inspect the current code and report the mismatch before editing the skill.
• Mark uncertain observations as unconfirmed.
• Keep this skill focused on durable project conventions, not one-off task notes.