From 6cda92f07b6e0f8364ef371e1260b9ba99903fd0 Mon Sep 17 00:00:00 2001 From: Connor Olding Date: Tue, 12 Jan 2016 16:12:53 -0800 Subject: [PATCH] update readme --- Lua/README.md | 228 +++++++++++++--------------------------------- Lua/lib/README.md | 111 ++++++++++++++++++++++ 2 files changed, 174 insertions(+), 165 deletions(-) create mode 100644 Lua/lib/README.md diff --git a/Lua/README.md b/Lua/README.md index 6ebc7e8..5138bf5 100644 --- a/Lua/README.md +++ b/Lua/README.md @@ -12,11 +12,6 @@ Note that some scripts lack full support for Ocarina of Time. ## Scripts -#### actor lister.lua -Lists actor data onscreen, -and focuses the camera on them. -Actors may be selected using the D-Pad. - #### cheat menu.lua Provides an onscreen UI for many features. Has four different input methods; @@ -26,7 +21,59 @@ Generally, it's opened with L and navigated with the D-Pad. #### count flags.lua Simply counts the number of scene flags globally set. -#### exit calculator.lua +#### inject.lua +Assembles and injects code into the game. + +#### m64p entry.lua +Ignore this for now. +This is a rough interfacing script for passing to mupen64plus, +and serves no purpose on Bizhawk. + +#### setup hundred.lua +Instantly gives you all the items in the game, etc. + +Does not set scene/event flags, +except the one required for the Great Spin Attack. + +#### setup race file.lua +Sets up a race file. + +A race file is a save in which the first cycle has been completed, +the Deku Mask has been acquired, +and some other details. + +#### test chests.lua +TODO + +#### test movement.lua +Tests the fastest form of basic movement in Majora's Mask. +Run it in the Clock Town Great Fairy's Fountain. + +### Monitors + +#### monitor actors.lua +Lists actor data onscreen, +and focuses the camera on them. +Actors may be selected using the D-Pad. + +#### monitor debug memory editor.lua +(Ocarina of Time) Used for determining which values +listed by the in-game debug memory editor are constant. + +#### monitor debug text.lua +TODO + +#### monitor epona.lua +used to investigate [this glitch with unloading Epona.][eponaglitch] + +[eponaglitch]: https://www.youtube.com/watch?v=kX0ZcIS8P84 + +#### monitor event flags.lua +Monitors event flags, +and announces which bits are being changed, +and if they have ever been seen changing before. + +#### monitor exits.lua Dumps information on the current exit value; scene name, entrance, entrance with unused offset; using human-readable English names. @@ -36,175 +83,26 @@ which produces [a large csv file.][csv] [csv]: https://eaguru.guru/t/_exits.csv -#### movement tests.lua -Tests the fastest form of basic movement in Majora's Mask. -Run it in the Clock Town Great Fairy's Fountain. - -#### inject.lua -Assembles and injects an assembly subroutine into the game. - -#### oneshot.lua -Instantly gives you all the items in the game, etc. - -Does not set scene/event flags, -except the one required for the Great Spin Attack. - -#### race.lua -Sets up a race file. - -A race file is a save in which the first cycle has been completed, -the Deku Mask has been acquired, -and some other details. - -#### room debug.lua -Parses and dumps the currently loaded room headers. - -#### m64p entry.lua -Ignore this for now. -This is a rough interfacing script for passing to mupen64plus, -and serves no purpose on Bizhawk. - -### Monitors - -These scripts look for changes in RAM regions and print them in detail. - -These are mostly used for documenation. - -#### epona monitor.lua -used to investigate [this glitch with unloading Epona.][eponaglitch] - -[eponaglitch]: https://www.youtube.com/watch?v=kX0ZcIS8P84 - -#### event flag monitor.lua -Monitors event flags, -and announces which bits are being changed, -and if they have ever been seen changing before. - -#### scene flag monitor.lua -Monitors the current scene's flags, -and announces which bits are being changed, -and if they have ever been seen changing before. - -#### misc monitor.lua +#### monitor misc.lua Monitors unknown regions of memory. Currently, this region is a chunk of save data, ignoring known addresses. -#### oot memory editor monitor.lua -(Ocarina of Time) Used for determining which values -listed by the in-game debug memory editor are constant. +#### monitor rooms.lua +Parses and dumps the currently loaded room headers. + +#### monitor scene flags.lua +Monitors the current scene's flags, +and announces which bits are being changed, +and if they have ever been seen changing before. #### watch animations.lua Monitors Link's used animations. ## Libraries -Or rather, scripts that have no functionality on their own. +See [the README in the lib directory][libs] for information. -#### depend.lua -Meant to override Lua's native `require` function, -to force reloading of the given script. - -This is useless outside of development. -In fact, this could cause bugs in code that depends on -`require` yielding the same tables twice. - -#### boilerplate.lua -Provides common functions used in the majority of scripts. -This should generally be imported before any other scripts, besides depend.lua. - -#### addrs/init.lua -Using boilerplate.lua's functions, -this provides the bulk of the interface to the games. - -Note that this particular initialization script populates the global namespace -with `version`, `oot`, `mm`, and most importantly `addrs`. - -#### addrs/basics.lua -Returns a table of tables of offsetable common addresses -between every known version of OoT and MM. - -**table keys:** - -* **link:** the bulk of the player's state in the game; -not to be confused with Link's actor. -most of this is saved to SRAM. - -* **global:** global context. -this is passed as an argument to many functions in the game's code -and contains a wealth of miscellaneous game state information. -this is actually allocated on heap, but its address never changes -— except on the file select screen? - -* **actor:** Link's actor. -this includes position, rotation, animation status, etc. -Link's actor is the only actor that -has the same address consistently, -as it's always the first one loaded. - -#### addrs/versions.lua -Returns a dictionary of md5 and sha1 hashes -of every known version of OoT and MM. - -The format of version strings is -`(O|M) (US|JP|EU)(1[0-9]|GC|DE|DB)( MQ)?`, -where: -* O: Ocarina of Time -* M: Majora's Mask -* US: American NTSC (United States) -* JP: Japanese NTSC -* EU: European PAL -* [two digits]: version number of a release build for the N64 -* GC: Gamecube -* DE: Demo (includes Debug features) -* DE: Debug -* MQ: Master Quest - -#### pt.lua -Dumps Lua tables as pseudo-yaml, -complete with references to prevent recursion. -Invaluable for debugging. -[Its repository is on gist][pt] — look there for basic usage. - -[pt]: https://gist.github.com/notwa/13fbddf05f654ba48321 - -#### extra.lua -Implements the `opairs` iterator function -and its helper functions, -providing iteration by sorted keys in alphabetical order. - -#### serialize.lua -Serializes (saves, dumps) Lua tables for later deserialization (loading). - -unlike `pt`, this dumps as Lua and cannot handle complicated (recursive) tables. - -#### messages.lua -Provides functions for printing onscreen, -such as printing for a given number of game frames. - -Also provides deferred printing, -to print to console all at once at the end of a frame, -which works around printing being otherwise slow on Bizhawk. - -#### flag manager.lua -Provides basic functions for poking at event flags and scene flags. - -#### classes.lua -For lazy people. -Populate the global namespace with all available classes, -excluding menu/interface classes. - -#### menu classes.lua -Provides various classes for implementing onscreen menus. - -#### menu input handlers.lua -Provides classes for interfacing user inputs with menus. - -#### menus/\* -Contains various submenus for `cheat menu.lua`. - -#### classes/\* -Contains various classes. -Note that the base `Class` function is defined in `boilerplate.lua`. +[libs]: /Lua/lib/README.md ## Data diff --git a/Lua/lib/README.md b/Lua/lib/README.md new file mode 100644 index 0000000..6ceb610 --- /dev/null +++ b/Lua/lib/README.md @@ -0,0 +1,111 @@ +## Libraries + +#### actors.lua +TODO + +#### classes.lua +For lazy people. +Populate the global namespace with all available classes, +excluding menu/interface classes. + +#### extra.lua +Implements the `opairs` iterator function +and its helper functions, +providing iteration by sorted keys in alphabetical order. + +#### flag manager.lua +Provides basic functions for poking at event flags and scene flags. + +#### boilerplate.lua +Provides common functions used in the majority of scripts. +This should generally be imported before any other scripts, besides depend.lua. + +#### lips.lua +TODO + +#### menu classes.lua +Provides various classes for implementing onscreen menus. + +#### menu input handlers.lua +Provides classes for interfacing user inputs with menus. + +#### messages.lua +Provides functions for printing onscreen, +such as printing for a given number of game frames. + +#### pt.lua +Dumps Lua tables as pseudo-yaml, +complete with references to prevent recursion. +Invaluable for debugging. +[Its repository is on gist][pt] — look there for basic usage. + +#### serialize.lua +Serializes (saves, dumps) Lua tables for later deserialization (loading). + +unlike `pt`, this dumps as Lua and cannot handle complicated (recursive) tables. + +Also provides deferred printing, +to print to console all at once at the end of a frame, +which works around printing being otherwise slow on Bizhawk. + +[pt]: https://gist.github.com/notwa/13fbddf05f654ba48321 + +#### setup.lua +TODO + +### addrs + +#### addrs/init.lua +Using boilerplate.lua's functions, +this provides the bulk of the interface to the games. + +Note that this particular initialization script populates the global namespace +with `version`, `oot`, `mm`, and most importantly `addrs`. + +#### addrs/basics.lua +Returns a table of tables of offsetable common addresses +between every known version of OoT and MM. + +**table keys:** + +* **link:** the bulk of the player's state in the game; +not to be confused with Link's actor. +most of this is saved to SRAM. + +* **global:** global context. +this is passed as an argument to many functions in the game's code +and contains a wealth of miscellaneous game state information. +this is actually allocated on heap, but its address never changes +— except on the file select screen? + +* **actor:** Link's actor. +this includes position, rotation, animation status, etc. +Link's actor is the only actor that +has the same address consistently, +as it's always the first one loaded. + +#### addrs/versions.lua +Returns a dictionary of md5 and sha1 hashes +of every known version of OoT and MM. + +The format of version strings is +`(O|M) (US|JP|EU)(1[0-9]|GC|DE|DB)( MQ)?`, +where: +* O: Ocarina of Time +* M: Majora's Mask +* US: American NTSC (United States) +* JP: Japanese NTSC +* EU: European PAL +* [two digits]: version number of a release build for the N64 +* GC: Gamecube +* DE: Demo (includes Debug features) +* DE: Debug +* MQ: Master Quest + +## menus/\* +Contains various submenus for `cheat menu.lua`. + +## classes/\* +Contains various classes. +Note that the base `Class` function is defined in `boilerplate.lua`. +