This blog post is meant to detail how to use the “Load Nexus Script” functionality in Dustmod.
What is Nexus TASing?
Nexus TASing allows you to feed Dustforce a sequence of inputs that can be played back directly in the game. This is different then the normal replay system as the play back can function within the nexus and can navigate the menu system.
TAS Script Format
TAS scripts are text files that will be fed into Dustmod. Dustmod will look for these files in a “tas” directory within the folder that contains the Dustforce executable. The scripts use a line based format. Each line is either a command or describes the inputs for a frame. Trailing whitespace or anything after a ‘#’ character is ignored for a line.
Input lines
Input lines are a sequence of 9 ‘1’s or ‘0’s describing whether each of the below inputs is pressed or not during the frame.
- left
- right
- up
- down
- jump
- dash
- light
- heavy
- escape
- taunt (as of v20)
Whitespace between each ‘0’ or ‘1’ character is ignored. As an example the line “010011000” describes a frame where right, jump, and dash are each pressed.
Command lines
Command lines are assumed to be any line that does not begin with a 0 or 1. Commands that take arguments should separate the command name and arguments using the ‘:’ character.
- LOAD – The LOAD command takes 3 parameters; character_id, save_id, level_file. character_id should be a number between 0-3 identifying the character to load. save_id should be name of the save file (see the ‘Creating a save file’ section) to load. level_file should be the file name of the level to load (e.g. “Nexus DX”).e.g.
LOAD:0:outsidedahlia:Nexus DX
- SYNCLOAD – Pauses the script until the first frame that your character can take inputs again. While the script is paused all inputs are set to 0.
SYNCLOAD
- STATS – Load a stats file containing key state, door state, and level scores. The command takes 1 parameter which is the identifier of the stat file to load which unfortunately currently needs to be an integer. You can copy a stats file in much the same way you would copy a save file for the LOAD command.
STATS:4 # Load in stats data from user/stats4
- INCLUDE – Execute commands from a script file. The script will begin executing this frame.
INCLUDE:tunnels.txt
- MOUSE – Sets the mouse state for the next frame. This command should appear before the input line that is meant to occur on the same frame. It takes 3 parameters, mouse x-position, mouse y-position, and mouse button state. Mouse positions can be found using the extended debug data display. Note that the origin (0, 0) is the center of the display and that the majority (all?) of menus in the game have fixed positions independent of game resolution.
MOUSE:75:-25:10000
Button state is a sequence of ‘0’ and ‘1’ characters that indicate the pressed state of the mouse related buttons in this order.
- Left Click
- Right Click
- Middle Click
- Scroll Up
- Scroll Down
Creating a Save File
Save files are used to initialize your position for a TAS. These are simply the checkpoint files already generated by Dustforce whenever you leave a nexus level. The intention is that this will allow TASers to accurately initialize their position in front of a starting door based on where it was originally entered in the previous segment.
Whenever you leave a nexus level your position information will be saved to “user/save/1_LEVEL_NAME”. For example when you enter downhill the game will save your position outside of the downhill door to “user/save/1_Nexus DX”.
To use a save in a nexus TAS script you should copy this save file and rename it to something like “user/save/outsidedownhill_Nexus DX” and then load it with a command like “LOAD:0:outsidedownhill:Nexus DX” at the start of your script.
Running a Script In Dustmod
To run a TAS script first create a folder in the Dustforce directory named “tas” and save your script within. Then within Dustforce navigate to Dustmod -> Tools -> Frame Advance. Then type the file name of your script (including any extension) into the ‘Load Nexus Script’ text area and push enter.
If successful your script should begin to execute. Pushing escape at anytime will terminate the script executation. You may also press F5 at to reload the script from the same file. If the file could not be loaded for any reason the text area will blank and nothing further will happen. Any format errors in the script itself will be silently ignored.
Give me an example script
LOAD:3:tunnels:Nexus DX # Give a couple inputs 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 100000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 010000000 000000100 001000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 001000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 000000000 100000000 000000000 100000000 000000000 100010000
Dustkid Blog 