ZShell: A Live debugging and cheat shell for ZC for Necromancer (2.556)+

[ZoriaRPG]

Some of you are probably aware, that since I've added the ability to type into ZScript, I've made a few text parsing modules.

Recently, I've given some thought to making a more portable version of my complex debug shell.

The one that I use is rather tightly woven into other things, and it isn't very easy for most people todeduce how it works. Therefore, I started again clean, writing something designed to run a single instruction in a shell, rather than a macro script.

This is now, tested and working. Press F7 to open the debug shell.

Demo Quest | Docs

FFC and Additional Visual and Audio Commands



In version 1.11, I added the ability to enqueue a series of commands at one time.
Press the down arrow key to enqueue an instruction!

Enqueued Commands


Basic Commands



Visual Commands



Sequence Scripts
You can store a sequernce of instructions as a sequence script, that you can run at any time by invoking RunSequence,id.



You may screate up to ten sequence scripts, that function like macros, and you can save them whenj you save the quest, so that you can easily design test macros (like shell/batch scripts).

If anyone is curious on how to do new, insane things, have a look at this beastie!

I designed the code in the link (above) so that when you press the F7 key (you can change this in the CFG settings), ZC opens a shell window. From there, you may type in any of the following commands:

Supported Instructions

Syntax and Usage

Tokens terminate by either a comma, or reaching the end of the string (NULL character).

If anyone is interested in using this, or if any of you are curious and have questions, please let me know. I may expand it to support multiple instructions and macros in the future, if there is any demand for that.

It also does not yet pause the action in ZC. I plan to add some ZScript functions to suspend all of ZC, except for scripts, just as the combo types Freeze All, and Freeze All (except FFCs), as Game->Freeze(int type, bool state), at some future point, so that scripts needn't use messy combo modification (or steal FFCs), in order to pause the game action.

The code for this should be both highly legible, and easy to modify. Adding instructions is relatively simple and straightforward, although you do need to add them in a few places--similar to adding ZASM and ZScript in the ZC Source files pertaining to ZScript (ffscript):

To Expand the Instructions
1. Define a case value after:
define LINKITEM = 12; //item, (BOOL), on / off

2. In the switch statement inside of int num_instruction_params(int instr),
add a case value for the new instruction, and return the number of params that it uses.

3. Determine the actual in-use instruction identifier, and create a caseset flow/entry for its characters, in int match_instruction(int token), returning the new case value on a match.

3. Determine the actual in-use instruction identifier, and create a caseset flow/entry for its characters, in int match_instruction(int token), returning the new case value on a match.

4. In the switch statement inside of void execute(), add the new case label, and give it instructions to call a normal ZScript function.

5. Args and Stack Size
The present stack supports up to two args, so, if you need more, you will need to modify the value of MAX_ARGS. The size of the stack is automatically determined and generated on compilation.


Script Syntax and Structure
This script makes use of a few new syntax features in ZScript, that require the latest Necromancer alpha builds. These include both typedef instructions, and script-local variables, arrays, and constants.

The details on these new mechanical ZScript components are a bit lengthy, so, for the sake of those shy of <tl;dr>, I'll put it all in a spoiler tag...

Spoiler: show

These are not the same as 'local variables' and ;local arrays', that you would list inside the run() function. They are still global, but their identifiersare within the local namespace of the script.

Essentially, this script turns an ffc script into a pseudo-namespace in syntax. (It's primarily for the sake of organising identifiers, and preventing global namespace pollution, although it isn't technically a real namespace.)

1. You may access to the stack[] globally as debugshell.stack[].

2. Likewise, all of the local defines, and SP are available as debugshell.DEFINITION and debugshell.SP, respectively.

3. Essentially, jyou access the script-local functions, variables, and arrays in precisely the same manner as the exant script-local functions. Keep in mind that when you do this, that variables and arrays become part of the global memory map, so you should limit this to things that have a purpose at a global scope.

Constants (defines) still use no stack space, and they are resolved during compilation.

4. From within the script that contains the local declarations, you call all of these by their local identifier, so script name resolution is not required. Thus, the namespace script debugshell calls stack[], WINDOW_F_KEY, and execute(); but from another script (or from the global namespace, you would use debugshell.stack[], debugshell.WINDOW_F_KEY, and debugshell.execute(), respectively.

The global script test, does precisely this, when it calls debugshell.process().

5. Note that none of this namespace handling is mandatory to make this script feasible. It simply makes it cleaner (IMO), and ensures that the global namespace of the user isn't polluted by conflicting identifiers. I've started doing this for all of my script sets--putting functions and large arrays inside of class scripts, namespace scripts, and struct scripts.

All of these are still ffc scripts--they can be any type, but I arbitrarily use ffc--but they don't often have anything inside the body of run(), living their lives as fancy containers.

Those of you worried abour running out of ffc script slots, should also note, that you do not need to assign a script to a slot to use its namespace. You need only assign scripts to slots if you need to execute the run() function of that script.

I think that covers the syntax in use here, and I hope that all--or at least some--of you, find it interesting and useful.