From 6bb341437b655ee2af3f1e1710c0b07e2ea6507d Mon Sep 17 00:00:00 2001 From: Connor Olding Date: Wed, 16 Dec 2015 02:53:31 -0800 Subject: [PATCH] describe Lua scripts --- Lua/README.md | 209 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) create mode 100644 Lua/README.md diff --git a/Lua/README.md b/Lua/README.md new file mode 100644 index 0000000..f422ee5 --- /dev/null +++ b/Lua/README.md @@ -0,0 +1,209 @@ +# Zelda 64 Lua Scripts + +These are written for +[the latest revision of Bizhawk,][biz] +but some compatiblity is provided for +[a fork of mupen64plus with Lua support.][m64p-lua] + +[biz]: https://github.com/TASVideos/bizhawk/ +[m64p-lua]: https://github.com/notwa/mupen64plus-core + +Note that some scripts lack full support for Ocarina of Time. + +## Main Scripts + +### main.lua +Ignore this for now. +This is a rough interfacing script for passing to mupen64plus, +and serves no purpose on Bizhawk. + +### actor listor.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; +refer to the comment near the start of the script. +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 +Dumps information on the current exit value; +scene name, entrance, entrance with unused offset; +using human-readable English names. + +Provides the function `dump_all_exits(fn)` +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. + +### 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. + +## Monitors + +These scripts look for changes in RAM regions and print them in detail. + +These are mostly used for documenation. + +### 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 +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. + +### watch animations.lua +Monitors Link's used animations. + +## Libraries + +Or rather, scripts that have no functionality on their own. + +### 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`. + +## Data + +Any data (that isn't provided by the games themselves) +is located in the data directory. + +Much of this should be self-explanitory. However, +files beginning with an underscores contain serialized tables +(generally from monitor scripts) +and usually won't make sense out of context.