SO YOU WANNA LEARN ACS

What permissions do you give others to modify and/or maintain your submission?: Modify: YES - Maintain: YES - I give permission for my entire submission to be modified by others or used in their own work. I give permission for my entire submission to be maintained by others as well.

hey hey hey
you wanna use scripting but dunno how????

SO YOU WANNA LEARN ACS

what the fuck is this

ACS (Action Code Script) is a scripting language created by Raven Software for Hexen. It’s an advanced, C like language designed for scripting events in your Doom maps. ZDoom, a source port of Doom, has since expanded the language's capabilities, like adding functions, arrays, and named scripts.

For the sake of simplicity and to not make you (the reader) scour for outdated information, Ring Racers uses the ZDoom ACS specification, and therefore all ACS language features and additions made for ZDoom will work with Ring Racers as well.

SETTING THINGS UP

Create a new map in Ultimate Zone Builder or High Voltage Ring. If you still don’t know how to do this, consult the two RR mapping documents pinned in the #custom-courses channel in the Kart Krew discord. I also recommend having some C knowledge before doing things, so go do that!

"is this possible in Ultimate Zone Builder?"

No, as the script editor is forcefully disabled there.

For the sake of example, I will be replacing the Test Run map here.

AD_4nXfsNNX0k9fJQTAud0Gvt2eUshbx3LWo8KKFEqoSFB9c-Wc30bcFixcs-lnsFkuU5hwSkOXafyLymDA3EWZxzoTuWefzUFBoiM-r3ZtDOUHCQKLo0RpQvST6Kk2TYkIkcRV3aeyuZdqypOfeWDgItGwcDqMv

Press F10. This will bring up this window, which is known as the Script Editor. This will be the place where you’ll write your scripts.

AD_4nXcwluMY1G5JfwuVCKo5L_mrtdV6xCwQUUu1eKyqG4Iyy0uNqzo95MOHV2PfgleuEh_-Mu9oYkNcKbnnfAk-jARYryhLe39h6oahFTp3V53k855p4KmNgEDKRivOy1AWALYg0sQfP6cp0jE8PRFdAxhiKmzC

Now that you’ve set things up, let’s go ahead and create our first script!

YOUR FIRST SCRIPT

Copy and paste this snippet of code to the script editor window. I will be breaking down the script one line at a time to tell you what it does.

The sample:

#include "rrcommon.acs"

script "HelloWorld" OPEN
{
    Delay(2*TICRATE);
    PrintBold(s:"Hello world!");
}

Your script editor should now contain this.

AD_4nXdjnha7wR7wIRjn3xMCejgvKfPJWLzWgwwvtby6JgaubkdPvIMCZ5sZYMJC8uNraW8J7gzgnQQ3QjLb6bJLxUuV6d01sGCZnqGk-n7YPpTPnO7ZiawBmNdh1K1flbq5msOfQ-jkdHuMcwoUzGxpJufRcLp-

BREAKING DOWN

An include:

#include "rrcommon.acs"

This line tells the compiler to ‘include’ a file. In this case, the file in question is rrcommon.acs, which is crucial if you want to script anything. The file contains definitions for functions that we’ll use. Without it, we won’t be able to properly interface with the game from the script!

A script definition:

script "HelloWorld" OPEN

The script part denotes that we are creating a new script block. The name of the script is “HelloWorld”. The script also runs at the start of the level, via the OPEN script type.
The name of the script in this case can be anything, since it gets run during the start of the level anyway. The script type denotes if this script should be called during an event. OPEN denotes this script should be run at the start as previously mentioned.
There are other script types that will not be the biggest focus in this part but will be useful.
- OPEN - Runs on level load.
- ENTER - Runs on level load, per player. Use ActivatorTID() to get the thing id of the player who ran the script. (Thing IDs will be explained later.)
- LAP - Runs on a lap change. Like ENTER, use ActivatorTID() to get the thing id of the player who ran the script.
- POSITION - Runs on the start of the position segment.
- OVERTIME - Runs on the start of overtime.
- UFO - Runs on the start of the sealed star special stages (?).
- EMERALD - Runs when you collect the emerald during special stages.
- FINISH - Runs on player finish. Like ENTER, use ActivatorTID() to get the thing id of the player who ran the script.

The code block:

{
    // ... code goes here
}

This is a block. You’ll put your code within this.

A function call:

Delay(2*TICRATE);

This makes the script pause execution for 2 seconds. 1 second is 35 ticks, and TICRATE is a constant value of 35.
Nothing below this function will run until 2 seconds have past.

Another function call, with a visible effect:

PrintBold(s:"Hello world!");

Prints the string Hello World! to the screen of every player.
The s: part denotes what type should we print to the screen. In this case, s: refers to a string, and can be omitted if we’re just passing a string directly. Please refer to https://zdoom.org/wiki/Print for info regarding item syntax.

Now, save the script, and see what happens when you test your map!

Good job!

LINEDEF TRIGGERS AND YOU
Scripts can not only be run during specific hardcoded events, it can also be run as part of gameplay!
Crossing over linedefs with an action can yield a script, so let's use them!

Let’s start by selecting the northern linedef here from our initial setup and giving it linedef action 475, and ticking the ‘Repeatable action’ and ‘When player crosses’ checkboxes in the activation section in the properties panel.

AD_4nXc-W_af8A8DHNRj4JMyxC5NcElCmKJrL6VmtyvHUYd8izmlyZFgseS6JoSsmmqbM6STJy4gdPmc98dlXvF_MMHKMjuJPuXXsAjctcqZvXiKiAQ3UoFTtwHC-ZkxbBpEz-kbPtjfYbmswHiOwc_BFFJuML1B

AD_4nXcMXtRXyoQWlyBsmFUMKnAsjS3eeAhLR0oHzKRkj9bj5e2I2tERu6xVyEsZyIyxdHATvv7CTbA98u-h4TJN95TIGYI5A3J1lfsmDU-X21w9Pia3D57Ijk9ruwxNvY1HTz9pqY8iuJhzQxuQX6wURuvwhhA

FOR THE TURBO NERDS AND UNDERSTANDERS:

‘Repeatable action’ makes the action always run even if we’ve crossed it before.
‘When player crosses’ makes the action only run if a player crossed over it, and not another object (like orbinauts, pushable objects, and other things)
The ‘Script name’ argument is something we’ll come back to later.

Let’s test our map and……. nothing happens. What gives?

That’s because we haven’t attached a script for that line yet, of course! Copy paste this snippet of code to your script editor, adding on to what we already had earlier.

Yet another sample:

script "LinedefExample" (void)
{
    Dialogue_SetSpeaker("eggman", 0);
    Dialogue_NewDismissText("Did you expect anything special?");
}

AD_4nXfru0q0jVatekaYbVqHgPtdidXGcPYZY4FFjtrtcSnpmRgKZlZqjbyYPHlCuMXcaXv1B8l8Lwo9V6eHFYDsmFCXCiS_emmvNy5qqXl5iumNdH9RDquF32oVM2pbbBLP_ZNvtmho08PW0Eg_2Mn__C8pcbjt

Your script editor should now look like this. Once that’s over with, set the ‘Script name’ parameter on your line earlier to “LinedefExample” via the dropdown!

AD_4nXdsZfokW1tm1BR9h15X-U9MV0HKJVMSCJ9QZAN5R3DKzly-uqcjuPHF7LCmtxZqgQOAXlLNO3S8_VHCUSb_eCNq0dXQZXcTi8U2PwzkEYSb_6h6FtmKp1O1-Nxcq5-PkvtKuygn53od4RGgDB6RZZnsW2Ln

Let’s test our level again aaaand…..

oh shit a talking egg

Now, what’s happening here? Well, we just ran some dialogue!

The Dialogue_ functions provide interfaces for dialogue scenarios, a la the Tutorial. For the sake of simplicity I will not go over that, as I want you to figure that out for yourself!

Do note that linedef script execution isn’t just for dialogue, it can be used for ANYTHING!

AD_4nXdXdlecD9BGywNale6W4IafOSUn8gWb0WOPmmdXdfiZFhhR712VUdD7Sa4LwrjNiZYIFKUiP4is3yVERrdhEUJofC8UyCFRjFI4iUoTrn5B-xJiLCeV4KI5LdCFacXDBC-CH1Z5niinApKyOSpK2xF2EHM

In this example, the function Sector_MovePlanes is responsible for the sector of tag 1 (the sector moving in front of us) to move up 256 units at a speed of 8. It then waits for the sector to finish moving via the TagWait function, then waits for half a second, then initiates dialogue with Eggman.

now what

This is where the document ends, at least. I don’t want to pad this document further than it probably should.
Let your imagination run wild!

And remember, check the ZDoom wiki for stuff you don’t know in terms of the language itself, and check rrspecial.acs in the files of your HVR folder! (Compilers/RingRacers/lib/inc/ACS/rrspecial.acs)

Reactions: Dark94, Aquavine, ChaseSP and 5 others

SO YOU WANNA LEARN ACS

More resources from haya__

Share this resource