ZPolyobject - ZScript Polyobject Library

[mikolah]

ZPolyobject - ZScript Polyobject library
This library adds Polyobject support to ZScript.

It makes querying polyobject state, such as current position, velocity and rotation, possible from within ZScript. In addition, it allows polyobject behavior to be customized through polyobject effectors.

Originally I wrote this code a while back for Dynamo's WIP Wolf3D-based mod, but I think it might also be useful on its own as a standalone library.

The code is heavily commented, so make sure to look through the source if you need any help.

Download link


Examples
Here are some code snippets showcasing basic usage:

---

Including

Code: Select all

#include "ZScript/Polyobjects/Polyobjects.zs"

Querying basic info

Code: Select all

/* ... */

// Print some info for polyobject 123
PolyobjectHandle po = PolyobjectHandle.FindPolyobj(123);
Console.Printf("Origin: %f %f", po.GetOrigin().x, po.GetOrigin().y);
Console.Printf("Current Position: %f %f", po.GetPos().x, po.GetPos().y); 
Console.Printf("Current Angle: %f", po.GetAngle());

/* ... */

Iterating through polyobjects

Code: Select all

/* ... */

PolyobjectIterator it = PolyobjectIterator.Create();
PolyobjectHandle po;
while ((po = it.Next()) != NULL)
{
    Console.Printf("Polyobject %i is rotated by %f degrees", po.PolyobjectNum, po.GetAngle());
}

/* ... */

Effector
First, create an effector by inheriting from PolyobjectEffector:

Code: Select all

class ExamplePolyobjectEffector: PolyobjectEffector
{
    // void OnAdd() is run immediately after the effector is added by PolyobjectHandle
    override void OnAdd()
    {
        // self.Polyobject holds a reference to the affected polyobject
        Console.Printf("Added by polyobject %i", Polyobject.PolyobjectNum);
    }

    // void PolyTick() is run every tic
    override void PolyTick()
    {
        // If too far away from initial position, return back
        if (Polyobject.GetPosDelta().Length() > 512)
        {
            Polyobject.MoveTo(NULL, Polyobject.GetOrigin(), 64);
            Console.Printf("there's no place like home");
        }
    }
}

Then pass an effector instance to PolyobjectHandler.AddEffector() method:

Code: Select all

/* ... */

let it = PolyobjectIterator.Create();
PolyobjectHandle po;
while ((po = it.Next()) != NULL)
{
    ExamplePolyobjectEffector poe = New('ExamplePolyobjectEffector');
    po.AddEffector(poe);
}

/* ... */

Advanced examples
There are two examples in /ZScript/Examples/ directory inside the .pk3 file:

---

Automatic sound blocking/unblocking (PolyobjectDoorSoundBlockEffector.zs)

This effector keeps track of whether a polyobject door is open or closed, and sets/unsets the "block sound" flag on linedefs of its surrounding sector accordingly.

Wolf3D-like door behavior (PolyobjectWolfensteinDoorEffector.zs)

This effector gives polyobject door a more Wolf3D-like behavior:

1. The door will stay open if a player or a monster is in the way, and won't close until
there's nothing blocking it.
2. If the door has started closing, using it will immediately make it open again.

A small test map is included, go to MAP01 to see them both in action.

Usage
Feel free to use this library in your projects, as long as you credit me.
Licensed under the MIT License.

Credits
Dynamo, for helping me find and fix bugs

[Gez]

Nice! The advanced effect examples in particular, I can see them becoming staples of future projects.

[Dynamo]

Not much I can say other than this is an absolutely fantastic package, which has been absolutely vital for my mod's continued progression. A hundred thumbs up

[Redneckerz]

Brilliant stuff. Worth putting up for the ZScript wiki article perhaps, or do you want to flesh it out a little more?

[mikolah]

Sure, that would be great!
There are some minor features I want to add at some point in the future (building a list of all linedefs that belong to a polyobject, methods that incapsulate calls to polyobject action specials, etc), but it's already fully functional as is.

[Redneckerz]

Oh i just connected your username with that other thing you are known for - Mikoveyors I have saved this as a link.

[prosto]

Hello, can you add methods for rotation to absolute angle, in degrees. Using these specials as a base
https://zdoom.org/wiki/Polyobj_RotateLeft
https://zdoom.org/wiki/Polyobj_RotateRight

If you can't, I'll make it by myself, because I need this. But I think, as the author, you can make it in the proper way. Or I can do it by myself, and then you'll update it with my patch (maybe 1-2 month later)