[ACS] Useful libraries for ACC/BCC/GDCC
Posted: Fri Oct 04, 2024 7:46 pm
This set of libraries is mostly for GDCC-CC, GDCC's C front. But some are for vanilla ACC, so do take a look even if you don't use GDCC.
Github repository
rt_iter
RadiusThingIterator. Much like ZScript's BlockThingsIterator this set of functions allows iterating through multiple actors in a radius around a reference actor or a point in space. RadiusThingIterator_Create will set up the interator with the specified reference actor (or point if using RadiusThingIterator_CreateFromPos), and from then on you can call RadiusThingIterator_Next in a while loop to set the activator to the next actor found within the range and with the specified flags. Once iteration is done (or RadiusThingIterator_Destroy is called), the next function will return false and automatically restore the original script activator (if any).
Headers are available for both BCS and C, featuring proper type support. Note that RadiusThingIterator_Create must be followed by either a completed iteration with RadiusThingIterator_Next or an explicit termination with RadiusThingIterator_Destroy, without any Delays in between or any call to RadiusThingIterator_Create again.
ptrace
NOTE: decorate.ptrace is required for proper functionality.
A pseudo-linetrace library. Much like ZScript's linetrace or QuakeC's trace, allows tracing a hitscan line, and get information about it. Things like where the trace ended (can be in mid-air, even), if it hit anything, the total distance between the start and end of the trace and a temporary (1-tic) TID to whatever actor it hit, if any. All information is returned in PTrace_Data after calling the PTrace function. In ACC, it's accessed as follows:
In BCC and GDCC (both fronts), there's headers available, which allow for much nicer access as a struct, as well as proper type support:
Note that all necessary information must be retrieved immediately after calling the function. Subsequent calls to PTrace will overwrite this struct, and Delays also risk the same thing (and after a single tic the hit actor TID will be invalidated).
paketlib
A library for Zandronum written in plain ACS (BCS and C headers to use the enhanced language features are available, too) that allows creating packets, sending and reading them over the network very easily. As an example:
It's decently light on bandwidth usage as well. Overhead is a mere 1 extra byte for each 8-32bit integer/fixed point number/bool, and only 3 extra bytes for an entire string.
ACS_Common
Files: ACS_Common.c, ACS_Common.h
A header for GDCC meant to simplify writing code without libGDCC and libc, and for code intended to be ported from ACC/BCC. It does the following:
actorlib
Files: actorlib.c, actorlib.h
A library making use of GDCC's struct properties to provide an ActorT struct that can call many functions in a more seamless way. For example:
It also provides a global called self, in much the same vein as QuakeC. This allows referring to the script activator without any extra definitions:
safe-malloc
Files: safe-malloc.c, safe-malloc.h
DEPRECATED, NO LONGER NECESSARY WITH CURRENT LIBGDCC
A replacement for libGDCC aimed at simplifying mod interop/compatiblity. Performs memory allocation always starting from near the very top of the address space. Other copies of safe-malloc can coexist without issue since they're all aligned, and regular ACS mods using the same global array are very unlikely to run into any conflicts.
This also allows moving the static allocation base for your mod/libc without affecting the starting location of the heap.
Must be linked as a replacement to libGDCC, do not include the original library!
Github repository
rt_iter
RadiusThingIterator. Much like ZScript's BlockThingsIterator this set of functions allows iterating through multiple actors in a radius around a reference actor or a point in space. RadiusThingIterator_Create will set up the interator with the specified reference actor (or point if using RadiusThingIterator_CreateFromPos), and from then on you can call RadiusThingIterator_Next in a while loop to set the activator to the next actor found within the range and with the specified flags. Once iteration is done (or RadiusThingIterator_Destroy is called), the next function will return false and automatically restore the original script activator (if any).
Code: Select all
RadiusThingIterator_Create(0, 256.0, RTIF_MONSTERS|RTIF_NOSIGHT|RTIF_CUBE);
while(RadiusThingIterator_Next())
{
SetActorVelocity(0, 0.0, 0.0, 16.0, true, false);
}ptrace
NOTE: decorate.ptrace is required for proper functionality.
A pseudo-linetrace library. Much like ZScript's linetrace or QuakeC's trace, allows tracing a hitscan line, and get information about it. Things like where the trace ended (can be in mid-air, even), if it hit anything, the total distance between the start and end of the trace and a temporary (1-tic) TID to whatever actor it hit, if any. All information is returned in PTrace_Data after calling the PTrace function. In ACC, it's accessed as follows:
Code: Select all
PTrace_Data[PTRACE_HIT]
PTrace_Data[PTRACE_POS_X] // y and z as well
PTrace_Data[PTRACE_HIT_ACTOR]
PTrace_Data[PTRACE_DISTANCE]Code: Select all
PTrace_Data.hitType
PTrace_Data.posX // y and z as well again
PTrace_Data.hitActor
PTrace_Data.distancepaketlib
A library for Zandronum written in plain ACS (BCS and C headers to use the enhanced language features are available, too) that allows creating packets, sending and reading them over the network very easily. As an example:
Code: Select all
#library "pakttest"
#include "zcommon.acs"
#import "paketlib.acs"
Script "lol" OPEN
{
str p = Packet_New();
p = Packet_Append(p, 1122334499, PACKET_WORD);
p = Packet_Append(p, 0, PACKET_WORD);
p = Packet_AppendStr(p, "This is a test");
p = Packet_Append(p, 13.5, PACKET_WORD);
Packet_Send("ClientReceivePacket", p, -1);
}
Script "ClientReceivePacket" (int p) CLIENTSIDE
{
p = Packet_Read(p, PACKET_WORD);
int i1 = Packet_Rval;
p = Packet_Read(p, PACKET_WORD);
int i2 = Packet_Rval;
p = Packet_ReadStr(p);
str s = Packet_Rval;
p = Packet_Read(p, PACKET_WORD);
int f = Packet_Rval;
Log(i:i1);
Log(i:i2);
Log(s:s);
Log(f:f);
}
ACS_Common
Files: ACS_Common.c, ACS_Common.h
A header for GDCC meant to simplify writing code without libGDCC and libc, and for code intended to be ported from ACC/BCC. It does the following:
- Enables ACS strings by default, and defines a str alias to them.
- Enables the fixed point type for literals by default.
- Includes ACS_Zandronum.h, as well as stdbool.h and stdfix.h to provide the remaining ACS types.
- Defines ACS_SHORT_NAMES so ACS functions are included without the ACS_ prefix.
- Adds a def_local macro to use inside functions, to allow using local arrays without requiring libGDCC.
- Adds a set of printing macros taking advantage of macro magic and _Generic (Can be used like: Print("This is a number: ", 10, (char)'.');).
- Adds the LanguageLookup, GetPrintName and IntToHex macros to cover the gaps not covered by the print functions.
actorlib
Files: actorlib.c, actorlib.h
A library making use of GDCC's struct properties to provide an ActorT struct that can call many functions in a more seamless way. For example:
Code: Select all
ActorT monster = {someMonsterTID};
monster.health = 200; // calls ACS_SetActorProperty(0, APROP_Health, 200)
if(monster.height < 32.0) // calls ACS_GetActorPropertyFixed(0, APROP_Height)
{
monster.speed = 32.0;
monster.scaleX = monster.scaleX - 0.1;
}Code: Select all
self.giveInv("Shotgun", 1);
self.health = 150;
self.viewHeight = self.height - 2.0;Files: safe-malloc.c, safe-malloc.h
DEPRECATED, NO LONGER NECESSARY WITH CURRENT LIBGDCC
A replacement for libGDCC aimed at simplifying mod interop/compatiblity. Performs memory allocation always starting from near the very top of the address space. Other copies of safe-malloc can coexist without issue since they're all aligned, and regular ACS mods using the same global array are very unlikely to run into any conflicts.
This also allows moving the static allocation base for your mod/libc without affecting the starting location of the heap.
Must be linked as a replacement to libGDCC, do not include the original library!