A scroll that dynamically detects and provides an interface to create classes for the game Shattered Pixel Dungeon and its mods while running the game.
This repository can be added without impacting the functionality of the implementing project if desired.
-
Obtain a fork of https://github.com/00-Evan/shattered-pixel-dungeon that is updated to be at least consistent with v1.0.0.
-
Implement Scroll of Debug via one of the following methods described below.
-
Ensure the code compiles.
- If the directory
shatteredpixel.shatteredpixeldungeonwas changed in the fork, a mass find and replace must be done for the scroll to work properly.
- If the directory
Scroll of Debug has 4 active "implementation" branches based on various places in Shattered's commit history as well as the history of Scroll of Debug itself.
git pull https://github.com/zrp200/ScrollOfDebug shpd/VERSION/IMPLEMENTATIONWhere:
VERSIONis one of1.0or1.3IMPLEMENTATIONis one ofpc-onlyorapk_support
It is possible to upgrade from 1.0 to 1.3 and from pc-only to apk_support with no Scroll of Debug-related conflicts due to the nature of how the branches are implemented.
If you want to avoid pulling in Scroll of Debug's admittably cursed commit history, add a --squash argument to the command.
Currently, the version ranges supported are:
Note: Scroll of Debug is developed on the latest Shattered by default, so the 1.0 branches may be updated a bit more slowly when features have to be changed during backporting to ensure compatibility.
There are two variants of Scroll of Debug: the minimal pc-only implementation, and the invasive apk_support implementation that allows Scroll of Debug to work properly on Android devices.
The pc-only branch is a direct implementation of the project via the subtree method (described later).
The only added change is to GameScene.java, where the Scroll of Debug is automatically added to the hero's inventory whenever GameScene is loaded when the game is in debug mode (-INDEV suffix), and removes it automatically if the game is not in debug mode. This specific implementation ensures that Scroll of Debug is always available to the developer while preventing unintended leaks of the scroll to players.
However, this implementation does not have full functionality in Android builds --- the base implementation of Scroll of Debug will be unable to detect classes in .apk builds of the game, causing Scroll of Debug's reflection-based commands (give, spawn, set, seed, use, inspect) to not work properly (though variables may still work).
pc-only implementation is best when:
- You do not intend to share Scroll of Debug builds with others.
- You want to keep Scroll of Debug confined to one directory.
The apk-support implementation spreads out Scroll of Debug files across the implementing repository to ensure that Android builds have full functionality of Scroll of Debug.
It moves one of the core files (PackageTrie) to SPD-CLASSES, amends PlatformSupport to allow a custom implementation of class retrieval, and then provides a custom Android implementation of this to ensure classes are read correctly.
It is entirely incompatible with the subtree-based implementation of Scroll of Debug.
Note: You can upgrade from the pc-only implementation (or subtree implementation) to the apk_support implementation by pulling in the apk_support branch at any time. The apk_support branch is based on pc-only.
The master branch of the repository can be directly pulled using git subtrees:
git subtree -P core/src/main/java/com/zrp200/scrollofdebug add https://github.com/zrp200/ScrollOfDebug masterIt can then also be updated by replacing add with pull in the previous command.
Implementing it this way is effectively identical to pulling in the shpd/1.3/pc-only branch, but it will lack the GameScene.java changes that let Scroll of Debug actually get added.
As such, it is not the preferred way to implement it, but if you lack Shattered's commit history (or desire a custom method of giving access to scroll of debug in-game) for any reason it may be the only viable option for implementation.
There is virtually no difference between the subtree method and straight copy-pasting the files into core/src/main/java/com/zrp200/scrollofdebug.
Scroll of Debug lets the reader create virtually any game-related object with a single command.
A more actively updated documentation can be found in the wiki.
The main commands currently are:
give <item> [+<level>]--- places an item of the correspondingitemclass into your inventory. The level can be optionally specified.spawn <mob> [-p]--- spawns a givenmobsomewhere on the level.-plets you place the mob.affect <buff> [duration]applies the specifiedbuffto a selected mob.seed <blob>---use <class> <method> [ARGS...]--- which uses the corresponding method of the provided class. A method can also be appended to the end of thegive,spawn, andaffectcommands to act on the created entity.inspect <class>gives a list of defined methods and fields for the specified class.goto <depth>--- warps you to the target depth immediately.help [command]--- gives an overview on all supported commands. Specifying the command will give more information about that specific command.
The following classes are autofilled with the corresponding Dungeon object by default.
hero<Dungeon.herolevel<Dungeon.level
Sometimes we need to run multiple methods on a created object or otherwise store an object for later commands.
Scroll of Debug supports variables to make this possible.
The result of methods that create objects can be stored by starting the command with @<variable> where <variable> is the name you want it to be stored as.
Alternatively, existing entities can be selected directly by using @<variable> cell to select a cell or @<variable> inv to select from the inventory.
Once created, the variable can be used by using @<variable> in place of any class or argument of a command.
