Feature Proposal: Add support for portals in vscript

[ENDERZOMBI102]

Which component should be improved?

Other

Describe your suggestion

Abstract

Portals are the main feature of the Portal series, and in hammer we have a number of ways to manipulate them, but if one wants to go on a more script-y route, all that rest is to use the hammer entities anyway. This issue proposes to expose portals to vscript to allow to omit the use of hammer entities and generally allow the manipulation and reading of them.

Proposal

The proposed class to expose the portal entity allows to read the properties of a portal and its state, while also allowing to fizzle it and to change its linkage ID. It is not needed to follow strictly everything in this proposal.

// unsure on what it extends, or if inheritance is exposed to vscript, we assumed yes
class CPropPortal extends CBaseEntity {
    /**
     * The current state of the portal.
     */
    State GetState();

    /**
     * The other portal entity this portal is bound to.
     */
    CPropPortal GetPartner();

    /**
     * Whether this is the primary portal, or the secondary.
     */
    bool IsPrimary();

    /**
     * Color of the portal, should reflect the cvar set by the user.
     */
    Vector GetColor();

    /**
     * Fizzles this portal.
     * @param silent whether to play the fizzling sounds.
     */
    void Fizzle( bool silent );

    /**
     * Sets the linkage id of this portal, allowing to change its partner.
     * @param id new id to use.
     */
    void SetLinkage( int id );

    /**
     * Get the linkage id of this portal.
     */
    int GetLinkage();

    /**
     * Apply the transform matrices and return the corresponding position from the portal's partner.
     * @param position world position to transform.
     */
    Vector TransformPosition( Vector position );

    /**
     * Apply the transform matrices and return the corresponding angles from the portal's partner.
     * @param angles angles to transform.
     */
    Vector TransformAngles( Vector angles );

    /**
     * The state of a portal.
     */
    enum State {
        Open,
        Closed,
        Fizzled
    }
}

Last note

Comments, suggestions and improvements are welcome!

Edit 08/07/2023 - 6:17PM

Applied @TeamSpen210's suggestions

[TeamSpen210]

The effect origin and bounding box probably isn't necessary, since portals have their origin at the center, and would set their size to the size of the portal. I do have a suggestion for an additional pair of methods though - TransformPosition()/TransformAngles(). You'd pass a world position/angles to the method, it'd apply the transform matrices and return the corresponding position from the portal's partner. It's possible to do this already, but it'd be far more efficient to use the existing matrices that are probably already there.

[ENDERZOMBI102]

the effect origin and bbox would be used to check if an entity is inside a portal's range, was thinking it would be quite useful to define custom behavior of scripted objects

wouldn't TransformPosition() and TransformAngles() make more sense to be inside CBaseEntity? seems like something one would want to have for every entity and not just portals

[TeamSpen210]

No, because these would apply the transforms from one portal to another. For instance if you gave a position in front of the blue portal, it'd return the corresponding position behind the orange portal.

[ENDERZOMBI102]

ohhh i see! i had misunderstood their usage, now that would be very cool indeed!

once home i'll add those to the above proposal

~ender