[ACS] Useful libraries for ACC/BCC/GDCC

[TDRR]

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
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]

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:

Code: Select all

PTrace_Data.hitType
PTrace_Data.posX // y and z as well again
PTrace_Data.hitActor
PTrace_Data.distance

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:

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);
}

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:

• 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.

Remember to rename both modprefix_sta ocurrences to fit your project.

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;
}

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:

Code: Select all

self.giveInv("Shotgun", 1);
self.health = 150;
self.viewHeight = self.height - 2.0;

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!

[Fused]

Great work! I really hope custom compilers get some more attention when libraries like these are around to help develop mods. The fact that they make it so much easier is something that should be pointed out more.

[TDRR]

Agreed. They really do make life a lot, lot easier.

I'd also like to point out that GDCC has had a good wiki for a while now. It documents both the ACS and C fronts.
https://github.com/DavidPH/GDCC/wiki

If anyone knows some C, come check it out! The wiki documents all extensions GDCC adds to help it work with the ACS VM and the engine more completely, and there's even a getting started guide now.

[Fused]

Nice, the wiki seems to be a lot more descriptive on the ACS front too now compared to when I was using it. I hope it attracts more people.

[TDRR]

I've added an extra library to help simplify writing code that doesn't use libGDCC or libc (often useful for extremely strict compatibility demands). It also makes porting code from ACS/BCS quite a bit simpler, as it sets a lot of defaults to be closer to them.

[TDRR]

Added an extra library to help create packets to send over the network, in light of the recent `CLIENTSIDEONLY` bugfix that broke some mods depending on the broken behavior. It's fairly efficient on bandwidth and performance, the overhead is only 1 byte per byte/short/word, and 3 bytes for an entire string. The way it works is that you simply write the things you want to write in the order you want, it'll craft a string and send it over the network, and then you can read your packet back in the same order on the receiving end. And that's it!

Unlike the previous set of libraries, this one is written in plain old ACS to simplify adoption.

[Ivan]

Added an extra library to help create packets to send over the network, in light of the recent `CLIENTSIDEONLY` bugfix that broke some mods depending on the broken behavior. It's fairly efficient on bandwidth and performance, the overhead is only 1 byte per byte/short/word, and 3 bytes for an entire string. The way it works is that you simply write the things you want to write in the order you want, it'll craft a string and send it over the network, and then you can read your packet back in the same order on the receiving end. And that's it!

Unlike the previous set of libraries, this one is written in plain old ACS to simplify adoption.

What's the bugged behavior you mention here?

[TDRR]

CLIENTSIDEONLY used to (in some cases only it seems, like ACS spawn funcs) spawn the actor on the server as well, and you could run functions affecting the actor and they'd be networked to the client as well. This was unintended (and caused network usage very similar to not having the flag at all), but some modders noticed it and started taking advantage of the bug. When it was fixed, many complained because they were left with no alternative.

This is supposed to help with that and hopefully to avoid similar kinds of hacks in the future.

[TDRR]

I've updated paketlib with a pair of functions to get the current size of a packet, and the max size allowed by the current server configuration. These take into account the header all packets sent by SendNetworkString have.

Headers for BCS and C are available as well, so you can link them into your projects. Note that the C header does not import the library for you, since it's designed to allow you to choose whether to link statically or dynamically.

[TDRR]

Added ptrace, which is a library with a single function very very similar to ZScript's linetrace, or QuakeC's trace. Also included headers for BCS and both GDCC fronts.

Additionally, I've removed the leftover logs in paketlib, fixed a wrong function signature in the C header for that, and finally deprecated safe-malloc, since current libGDCC has rendered it obsolete.