ACSUtils - a library for ZDoom/Zandronum scripting

[Dj Skaarj]

---

My friend Korshun told me to post this because his account has been manually deactivated for some reason and he can't log in.

ACSUtils is a library for ZDoom and Zandronum scripting that contains over 256 functions. I made it because I found myself copying the same missing functions between projects over and over again.

ACSUtils includes a complete replacement for HudMessage with support for scaling and 3D HudMessages.

ACSUtils supports the latest released versions of ZDoom, GZDoom, and Zandronum.

Documentation: http://acsutils.strangled.net/doku.php?id=start
GitHub: https://github.com/Korshun/acsutils
Download: https://github.com/Korshun/acsutils/releases

If you think that a function can be useful for other projects, suggest it for inclusion in ACSUtils.

[wildweasel]

My friend Korshun told me to post this because his account has been manually deactivated for some reason and he can't log in.

Welcome to the forums. If you're in touch with Korshun, let him know I've fixed his account and he should be able to log in now. Sorry about that - fallout from an attempted hijacking of the forums.

[Nash]

Leaving my comment in here to check this out when I have time. Thanks for sharing!

[The Zombie Killer]

Took a quick look, here are some issues I found:

• the presence of GetCVarFixed will break compatibility with gdcc-acc, which is basically a non-shit ACS compiler (structs, automatic fixed point handling, etc). It'd have to be renamed to something else
• This is wrong:

  Code: Select all

  function bool StrIsAscii(str s)
  {
  	int len = StrLen(s);
  	for (int i = 0; i < len; i++)
  	{
  		str char = GetChar(s, i);
  		if (char < ASCII_START || char > ASCII_END)
  			return false;
  	}
  	return true;
  }

  the "char" variable should be of type "int". This also breaks compatibility with gdcc-acc

[TechnoDoomed1]

Pretty useful stuff all round. However, I noticed that there's no logarithmic function in the math section, something that is also lacking in default ACS as well (as far as I know, feel free to correct me if I'm wrong). Since I'm a math student, I'm considering writting a possible solution myself, although the ZDoom Wikia already has one.

It would also be appreciated if there was a function that allowed easy synchronization between octic-based events and tic-based events. Really, whose idea was to make a second last for 35 frames and then make a further subdivision that was not a divisor of said number?!

[Dj Skaarj]

@The Zombie Killer

the presence of GetCVarFixed will break compatibility with gdcc-acc, which is basically a non-shit ACS compiler (structs, automatic fixed point handling, etc). It'd have to be renamed to something else

Thanks for the notification. The function was renamed to "a_GetCVarFixed()", its name in the official documentation was fixed too.

the "char" variable should be of type "int". This also breaks compatibility with gdcc-acc

Heh, that was definitely a typo. Anyway, I've fixed it.

@TechnoDoomed1
Thanks for the reply! We'll do something about it.

Feedback is always welcome. We'll be doing our best to improve the quality of the library.

[Korshun]

Pretty useful stuff all round. However, I noticed that there's no logarithmic function in the math section, something that is also lacking in default ACS as well (as far as I know, feel free to correct me if I'm wrong). Since I'm a math student, I'm considering writting a possible solution myself, although the ZDoom Wikia already has one.

You are welcome to do so, and I will include it into ACSUtils! Thank you!

It would also be appreciated if there was a function that allowed easy synchronization between octic-based events and tic-based events. Really, whose idea was to make a second last for 35 frames and then make a further subdivision that was not a divisor of said number?!

Yeah this stuff is ridiculous. I remember seeing a function to do exactly that somewhere, but didn't think it was important enough to steal (maybe because I am not a mapper). I can find it again.

[Korshun]

ACSUtils 1.2.1 released with the fixes for GDCC that The Zombie Killer requested.

changelog

[TechnoDoomed1]

I coded a log algorithm, but my current implementation only works on fixed-point numbers. This means that to use on integers you have to convert them to fixed numbers first. If the other way around is preffered, just tell me, or feel free to change the code accordingly.

---

Code: Select all

//======================================================================================================================
/* fixed FixedNum (int x) 
   Converts an integer to a fixed number. */
//======================================================================================================================

function int FixedNum (int x) {
    return x << 16;
}

//======================================================================================================================
/* fixed log_2 (fixed x) 
   Returns the logarithm in base 2 of any fixed-point number, as a fixed number.
   To use on integers, you have to convert them to a fixed-point first. */
//======================================================================================================================

function int log_2 (int x) {
    // We calculate the integral and decimal parts of the bit logarithm of x.
    int integer_part = 0, decimal_part = 0;

    // The integral part is how many times we can divide by 2 until we reach a number in the range [1, 2).
    // If the number is on the range (0, 1) then we multiply by 2 until we reach a number in the range [1, 2).
    while (x < 1.0) {
        -- integer_part;
        x *= 2;
    }
    while (x >= 2.0) {
        ++ integer_part;
        x /= 2;
    }

    // Then, we square the number each time to get the next relevant byte, until we reach max precision allowed.
    // WHY? Because if 2^d = y, then (2^d)^2 = 2^(2d) = y^2, where d is the decimal part.
    //-----------------------------------------------------------------------------------------------------------------
    // Let's start with the fraction 1/2, and go downwards until we reach the max precision for a fixed-point number,
    // which is 1 (since it occupies the right side of the byte, it really represents 2^-16).

    int current_fraction = 0.5;

    while (current_fraction > 1) {
        x = FixedMul(x, x);
        if (x >= 2.0) {
            decimal_part += current_fraction;
            x /= 2;
        }

        current_fraction /= 2;
    }

    // We can finally return the number as the integral part (shifted 16 bytes to the left, to be on the corresponding
    // integral part of the fixed-point number) plus the decimal part, which is the sum of all the fractions of 2 that
    // correspond to the solution of 2^d = y.

    return (FixedNum(integer_part) + decimal_part);
}

//======================================================================================================================
/* fixed ln (fixed x) 
   Returns the natural logarithm of any fixed-point number, as a fixed number.
   To use on integers, you have to convert them into a fixed-point first. */
//======================================================================================================================

function int ln (int x) {
    // This calculates the natural logarithm of a number using the property that:   ln(x) = log_2(x) / log_2(e)
    // This is done because calculating the log_2 of a number is far easier, specially with fixed-point arithmetics.  

    return FixedDiv(log_2(x), log_2(MATH_E));
}

//======================================================================================================================
/* fixed log_b (fixed x, fixed base) 
   Returns the logarithm in an arbitrary base of any fixed-point number, as a fixed number.
   Base must also be a fixed number greater than 1.0
   To use on integers, you have to convert them into a fixed-point first. */
//======================================================================================================================

function int log_base (int x, int base) {
    // This calculates the logarithm in any base > 1.0, by using the property that:   log_b(x) = log_2(x) / log_2(b)
    // Otherwise, returns 0.

    if (base > 1.0)
        return FixedDiv(log_2(x), log_2(base));
    
    return 0;
}

[Korshun]

Wow! Thank you for the functions.

I coded a log algorithm, but my current implementation only works on fixed-point numbers. This means that to use on integers you have to convert them to fixed numbers first.

Math functions should accept whatever type is best for them. No auto conversions should be present. And I guess that a separate implementation should be used for integers, just like with zan_Sqrt and zan_FixedSqrt.

or feel free to change the code accordingly.

There are a few things that may be changed:

1. Should ACSUtils use your function names or follow the standard set by C?
2. FixedNum, come on, YET ANOTHER of those. Not that I blame you for using it, but ACSUtils already has itof added by Monsterovich for the same reasons as yours. I will replace it with itof or just plain conversion.

I will include the functions into the next release. We should decide on the naming.

[TechnoDoomed1]

Fine enough, though following C naming convention is going to be hard as far as log is concerned (that's already the name of a function in ACS, and function names are not case-sensitive to allow differentiation between the two). The convention of log_2 versus log2 depends on your whim, I care little for the naming really. Just knowing that my feedback or even code was helpful is enough, I'm not nitpicky.

I indeed agree that a function should accept data as generic as possible, but the problem is that both integers and fixed numbers are really the same type, you just make an arbitrary decision of considering them full integers or interpreting them as half integer, half fraction. Allowing for fixed numbers seemed like the most generic solution, since it can represent a wider amount of numbers (reals vs integers), although it's more limited in range. True floating point arithmetic would be best here, maybe even using Gauss' AGM formula to calculate the log() since it's quicker, but alas it's not possible in ACS.

As far as the implementation of yet another int to fixed number function when there's already one... sorry. Although I revised the docs to assess ACSUtils' usefulness for using it myself in the future, I've never used it yet.


PS:If you are not in a hurry, since it's almost midnight on my timezone, I'll try to do the integer version tomorrow. Shouldn't be too hard, really.

---

Code: Select all

function int i_log2 (int x) {
    // We calculate the integral and decimal parts of the bit logarithm of x.
    int integer_part = 0, decimal_part = 0;

    // The integral part is how many times we can divide by 2 until we reach a number lower than 2.
    // We lose precision by not keeping the fractional part until that part fits perfectly in a fixed number variable.
    while (x >= 32768) {
        ++ integer_part;
        x /= 2;
    }

    x <<= 16;

    while (x >= 2.0) {
        ++ integer_part;
        x /= 2;
    }

    // Then, we square the number each time to get the next relevant byte, until we reach max precision allowed.
    // WHY? Because if 2^d = y, then (2^d)^2 = 2^(2d) = y^2, where d is the decimal part.
    //-----------------------------------------------------------------------------------------------------------------
    // Let's start with the fraction 1/2, and go downwards until we reach the max precision for a fixed-point number,
    // which is 1 (since it occupies the right side of the byte, it really represents 2^-16).

    int current_fraction = 0.5;

    while (current_fraction > 1) {
        x = FixedMul(x, x);
        if (x >= 2.0) {
            decimal_part += current_fraction;
            x /= 2;
        }

        current_fraction /= 2;
    }

    // We can finally return the number as the integral part (shifted 16 bytes to the left, to be on the corresponding
    // integral part of the fixed-point number) plus the decimal part, which is the sum of all the fractions of 2 that
    // correspond to the solution of 2^d = y.

    return ((integer_part << 16) + decimal_part);
}

It's the log2 version for integers. Basically identical to the other one, but allows for integer numbers larger than 32768. The changes from here on to the rest of the functions is trivial. Inform me of any kind of problem or issue you find, as I finished it half asleep.

[Korshun]

Fine enough, though following C naming convention is going to be hard as far as log is concerned (that's already the name of a function in ACS

I forgot that there is that Log used for logging , but since log in C is natural logarithm, we can use ln for that and rename the rest to match C (if we will decide to do so).

I indeed agree that a function should accept data as generic as possible, but the problem is that both integers and fixed numbers are really the same type, you just make an arbitrary decision of considering them full integers or interpreting them as half integer, half fraction.

You are absolutely right, but 32-bit int and 16.16 fixed are the most common data types in ACS, and support for them is built into ACC. Yes, we are missing out on other fixed-point formats, but these two types will be used the most.

True floating point arithmetic would be best here, maybe even using Gauss' AGM formula to calculate the log() since it's quicker, but alas it's not possible in ACS.

It's possible implement software floating-point arithmetic in ACS. It just needs the following functions:

---

• FloatAdd
• FloatSub
• FloatMul
• FloatDiv
• IntToFloat
• FixedToFloat
• FloatToInt
• FloatToFixed

...and yet another set of math functions from C (but in this case their implementations can be copypasted from C libraries).
ZDoom ACS VM could also provide floating-point instructions.

But I am totally not not sure that there is any demand for it.

As far as the implementation of yet another int to fixed number function when there's already one... sorry. Although I revised the docs to assess ACSUtils' usefulness for using it myself in the future, I've never used it yet.

That said, your name is more readable, as I just mistyped "itof" as "atof" when writing the previous post, and that would result in a huge bug, as ACSUtils provides "atof", which parses a string into a fixed-point number.

PS:If you are not in a hurry, since it's almost midnight on my timezone, I'll try to do the integer version tomorrow. Shouldn't be too hard, really.

Thank you for the integer version, but there was no need to be in a hurry.

[TechnoDoomed1]

No worries.
BTW, I was checking the docs and found that IntDiv could use an improvement as per the team's instructions.

IntDiv doesn't work with parameters over 32767 or under -32768, it's just a shorthand for FixedDiv(a«16, b«16) right now.
Contributions to enable IntDiv to work with any integers as long as their ratio is less than 32767 are welcome.

Let me know what you think:

---

Code: Select all

//==================================================================================================================
/* fixed IntDiv (int a, int b)
    Divides two integers and returns a fixed-point result. 
    Allows division of any 2 integers whose ratio is not higher than 32767. */
//==================================================================================================================

function int IntDiv (int a, int b) {
    int quotient = 0, current_fraction = 1.0;

    // Only works when the ratio is less than 32767 = 2^15 - 1.
    // Otherwise return 0.

    if ((abs(a) / abs(b)) > 32767) {
        return 0;
    }

    // Performs the same algorithm as hand division, but working with powers of 2 instead of 10. 
    // This is done until we reach the maximum allowed precision, which is 1 (=2^-16 in fixed point).

    while (current_fraction > 1) {
        quotient += (a / b) * current_fraction;
        a = (a % b) * 2;
        current_fraction /= 2;
    }

    return quotient;
}

[Korshun]

This is great! IntDiv is now a really cool function!
Will include all the math into ACSUtils 1.2.2! (right after other ACSUtils devs voice their opinion about the naming of logarithm functions, a not-so-good reason to delay it, I know)

EDIT: I have found the octic synchronization function: http://zdoom.org/wiki/Syncspeed, do I just include it?

[TechnoDoomed1]

Seems like a good idea.

Though to be fair I find it a little convoluted to replace a measly cross-multiplication. Still useful, though.