From d4f2b5b51d8a2b6ff89678113d1e96bd7130a2a3 Mon Sep 17 00:00:00 2001 From: Malleo Date: Sat, 21 Oct 2023 00:30:11 -0400 Subject: [PATCH 1/5] Create PythonScripting.md Initial draft, still more to add probably --- docs/PythonScripting.md | 54 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) create mode 100644 docs/PythonScripting.md diff --git a/docs/PythonScripting.md b/docs/PythonScripting.md new file mode 100644 index 000000000000..bfd0505ecfad --- /dev/null +++ b/docs/PythonScripting.md @@ -0,0 +1,54 @@ +# PyCore Scripting Interface Specifications + +This document outlines how to begin writing your own Python scripts to interface with Dolphin. + +## Folder Hierarchy +Scripts and any user-defined helper files are located within `$DOLPHIN_USER_FOLDER/Load/Scripts`. The current folder hierarchy is defined as follows: + +``` +/Load/Scripts +\__ Modules (Directory) +\__ GAMEID (Directory) + \__ SCRIPTS GO HERE +``` +`GAMEID` can be one or multiple directories which are named after a game's ID without a region (e.g. `RMC` for "Mario Kart Wii (All regions)"). + +`Modules` is automatically created by Dolphin and is the preferred location for any Python modules that game-specific scripts may import. + +## Writing Scripts +Scripts can import various optional modules from dolphin, such as: + +- `memory`: Allows for scripts to read from / write to memory +- `event`: Supports listening for various events such as frame advances and savestate saves/loads +- `gui`: Grants the ability to render text and polygons to the imgui game overlay (useful for RAM Watch displays) + +For a full definition of modules, see [python-stubs](python-stubs). + +### Events +Events can be listened for in a few ways. Some events may provide arguments, such as whether a savestate load was via a file or a slot. + +- Callback +```python +@event.on_savestatesave +def my_callback(fromSlot : bool, slotNumber : int): + if (fromSlot): + print(f"Loaded from slot {slotNumber}") + else: + print("Loaded from file") +``` +- Async +```python +while True: + (fromSlot, slotNumber) = await event.savestatesave() + if (fromSlot): + print(f"Loaded from slot {slotNumber}") + else: + print("Loaded from file") +``` + +## Running Scripts +The scripts panel can be accessed either by going to `View->Scripting` or clicking on the `Scripts` toolbar button. This will open the scripting widget on the left side of the Dolphin window. This widget will show a list of all `.py` files present within `$DOLPHIN_USER_FOLDER/Load/Scripts` and its child directories. + +Upon loading a game, to hide scripts unrelated to the game you are playing, the widget will navigate to the `GAMEID` folder associated with the active game. If the associated `GAMEID` folder is not present, then the root Scripts directory will be shown. Closing a game will return you to the root Scripts directory. + +Scripts can be toggled by clicking the checkbox next to the script name. Even if a script is checked, it will not run until a game is booted up, and it will stop running when a game is shut down. From 9ed0f8c2c524890c3a56e094944327ec0ff031a9 Mon Sep 17 00:00:00 2001 From: Malleo Date: Sat, 21 Oct 2023 00:45:51 -0400 Subject: [PATCH 2/5] Fix stub link --- docs/PythonScripting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/PythonScripting.md b/docs/PythonScripting.md index bfd0505ecfad..8f13b9f6c62b 100644 --- a/docs/PythonScripting.md +++ b/docs/PythonScripting.md @@ -22,7 +22,7 @@ Scripts can import various optional modules from dolphin, such as: - `event`: Supports listening for various events such as frame advances and savestate saves/loads - `gui`: Grants the ability to render text and polygons to the imgui game overlay (useful for RAM Watch displays) -For a full definition of modules, see [python-stubs](python-stubs). +For a full definition of modules, see [python-stubs](../python-stubs). ### Events Events can be listened for in a few ways. Some events may provide arguments, such as whether a savestate load was via a file or a slot. From 021c6e35e87520535ec235589e9be73de2553597 Mon Sep 17 00:00:00 2001 From: Malleo Date: Sat, 21 Oct 2023 00:56:03 -0400 Subject: [PATCH 3/5] Add RAM Watch Example --- docs/PythonScripting.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/PythonScripting.md b/docs/PythonScripting.md index 8f13b9f6c62b..a2e34fa5902a 100644 --- a/docs/PythonScripting.md +++ b/docs/PythonScripting.md @@ -29,6 +29,8 @@ Events can be listened for in a few ways. Some events may provide arguments, suc - Callback ```python +from dolphin import event + @event.on_savestatesave def my_callback(fromSlot : bool, slotNumber : int): if (fromSlot): @@ -38,6 +40,8 @@ def my_callback(fromSlot : bool, slotNumber : int): ``` - Async ```python +from dolphin import event + while True: (fromSlot, slotNumber) = await event.savestatesave() if (fromSlot): @@ -46,6 +50,21 @@ while True: print("Loaded from file") ``` +### RAM Watch Example +The following example shows how to read and display a u32 located at address 0x80000000 every frame: +```python +from dolphin import event, gui, memory + +@event.on_frameadvance +def my_callback(): + value = memory.read_u32(0x80000000) + + position = (10, 10) + argb_color = 0xFFFFFFFF + text = f"{value}" + gui.draw_text(position, argb_color, text) +``` + ## Running Scripts The scripts panel can be accessed either by going to `View->Scripting` or clicking on the `Scripts` toolbar button. This will open the scripting widget on the left side of the Dolphin window. This widget will show a list of all `.py` files present within `$DOLPHIN_USER_FOLDER/Load/Scripts` and its child directories. From dbfa9c7a654b7597d2f1f5a8f9f68e6ec6ebda4e Mon Sep 17 00:00:00 2001 From: Malleo Date: Sun, 22 Oct 2023 22:19:51 -0400 Subject: [PATCH 4/5] Add all module explanations and explain autorun scripts --- docs/PythonScripting.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/PythonScripting.md b/docs/PythonScripting.md index a2e34fa5902a..701fed1c2b9e 100644 --- a/docs/PythonScripting.md +++ b/docs/PythonScripting.md @@ -16,15 +16,20 @@ Scripts and any user-defined helper files are located within `$DOLPHIN_USER_FOLD `Modules` is automatically created by Dolphin and is the preferred location for any Python modules that game-specific scripts may import. ## Writing Scripts -Scripts can import various optional modules from dolphin, such as: +Scripts can import various optional modules from dolphin. -- `memory`: Allows for scripts to read from / write to memory +- `controller`: Allows you to get/set controller information, for both Gamecube and Wii controllers +- `debug`: Supports manipulation of code and memory breakpoints - `event`: Supports listening for various events such as frame advances and savestate saves/loads - `gui`: Grants the ability to render text and polygons to the imgui game overlay (useful for RAM Watch displays) +- `memory`: Allows for scripts to read from / write to memory +- `registers`: Supports reading/writing to the PowerPC registers +- `savestate`: Allows for saving/loading states to/from a slot, file, or byte string +- `utils`: Various utility functions, such as starting/stopping framedumps, and toggling play For a full definition of modules, see [python-stubs](../python-stubs). -### Events +#### Events Events can be listened for in a few ways. Some events may provide arguments, such as whether a savestate load was via a file or a slot. - Callback @@ -71,3 +76,5 @@ The scripts panel can be accessed either by going to `View->Scripting` or clicki Upon loading a game, to hide scripts unrelated to the game you are playing, the widget will navigate to the `GAMEID` folder associated with the active game. If the associated `GAMEID` folder is not present, then the root Scripts directory will be shown. Closing a game will return you to the root Scripts directory. Scripts can be toggled by clicking the checkbox next to the script name. Even if a script is checked, it will not run until a game is booted up, and it will stop running when a game is shut down. + +Scripts with a filename prefixed by `_` will run automatically on game startup. This only applies to scripts within the `GAMEID` folder. Scripts in other directories will not run, even with the `_` prefix. From adb63e0a83af317a9f4149a6b1f55fa9f1ff1932 Mon Sep 17 00:00:00 2001 From: Malleo Date: Fri, 27 Oct 2023 11:11:01 -0400 Subject: [PATCH 5/5] Clarify GAMEID folder and subfolders, clarify Wii Remote capabilities with controller module --- docs/PythonScripting.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/PythonScripting.md b/docs/PythonScripting.md index 701fed1c2b9e..408feca26384 100644 --- a/docs/PythonScripting.md +++ b/docs/PythonScripting.md @@ -12,13 +12,14 @@ Scripts and any user-defined helper files are located within `$DOLPHIN_USER_FOLD \__ SCRIPTS GO HERE ``` `GAMEID` can be one or multiple directories which are named after a game's ID without a region (e.g. `RMC` for "Mario Kart Wii (All regions)"). +Subdirectories can be present and will be accessible during game run. Note that, if you organize subdirectories by region, Dolphin will still autorun any scripts with a filename prefixed by '_' present in the `GAMEID` directory and all subdirectories. `Modules` is automatically created by Dolphin and is the preferred location for any Python modules that game-specific scripts may import. ## Writing Scripts Scripts can import various optional modules from dolphin. -- `controller`: Allows you to get/set controller information, for both Gamecube and Wii controllers +- `controller`: Allows you to get/set controller information. Note that for Wii Remotes, the only motion supported via this module is pointing. - `debug`: Supports manipulation of code and memory breakpoints - `event`: Supports listening for various events such as frame advances and savestate saves/loads - `gui`: Grants the ability to render text and polygons to the imgui game overlay (useful for RAM Watch displays) @@ -77,4 +78,4 @@ Upon loading a game, to hide scripts unrelated to the game you are playing, the Scripts can be toggled by clicking the checkbox next to the script name. Even if a script is checked, it will not run until a game is booted up, and it will stop running when a game is shut down. -Scripts with a filename prefixed by `_` will run automatically on game startup. This only applies to scripts within the `GAMEID` folder. Scripts in other directories will not run, even with the `_` prefix. +Scripts with a filename prefixed by `_` will run automatically on game startup. This only applies to scripts within the `GAMEID` folder and any subfolders. Scripts in other directories will not run, even with the `_` prefix.