[VScript] regen.nut: Better Ammo Regen (limited regen + more!)

[Kingstripes]

regen.nut: Better Ammo Regen

Script download | Example map download (vmf) | GitHub repo

regen.nut is VScript to help with ammo regeneration, particularly limited regen jumps.
The script is broken into 3 parts, which are all shown in the following demonstration video:

1. Simple Limited Regen

In existing limited regen jumps, func_regenerate triggers operate on a 3 second, per-player cycle (m_flNextRegenerateTime). On jumps such as jump_soar level 16, it's possible to wallshot too fast and miss being regenerated if you were regenerated less than 3 seconds ago. Furthermore, you sometimes have to wait around at the start of a level to have full ammo if you were regenerated slightly before failing.

Simple limited regen provides a better alternative to func_regenerate for limited regen jumps:

• Instantly regenerates the player upon touching a simple regen trigger (e.g. at any point during the level or immediately after failing), with no 3 second timer
• Unlike func_regenerate, you can prevent lingering indefinitely inside a trigger for unlimited ammo because simple regen triggers only regenerate each player once per attempt at a level (by default)
• Unlike func_regenerate, simple regen triggers can be filtered by class either with a filter_activator_class entity or by supplying an optional class type when calling the main simple regen function (see Usage section)

Usage:

Spoiler (click to show/hide)

First, download the latest regen.nut file and place it in your Team Fortress 2/tf/scripts/vscripts folder. Then create a logic_script entity somewhere in your map:

• In the logic_script object properties, set "Entity Scripts" to regen.nut (do not use "Manage..." button, it is broken)
• Give the logic_script entity a name (e.g. "regen")

Simple limited regen includes 2 functions for you to use in Hammer:

• Regen() - Regenerates the player instantly. If it is the first time a player has touched this Regen() trigger, the trigger will be added to a list of touched triggers. This list is used to ensure that the player is only regenerated once by the trigger, until the list is reset with ResetTouched().
• ResetTouched() - Resets the list of triggers that the player has touched, allowing previously touched Regen() triggers to regenerate the player again.
  

Steps for adding simple regen functions to triggers:
- Create a trigger_multiple brush entity (or an any existing trigger entity, e.g. trigger_teleport)
    1. Open the trigger entity's object properties window
    2. Go to the Outputs tab
    3. Create an "OnStartTouch" output:
        - Target Entity = regen (or whatever you named your logic_script entity)
        - Target Input = RunScriptCode
        - Parameter = Regen() or ResetTouched()

While the placement of Regen() and ResetTouched() is largely up to you, I recommend the following guidelines:

• For most cases, have a trigger_multiple at the start of your jump that contains both Regen() and ResetTouched(). For any regen triggers during the jump, only use Regen(). Keep in mind that with this setup, the starting trigger will allow the player to be regenerated every time they enter the trigger.
• If you want to ensure the player is only regenerated once at the start of a jump, then I recommend the following:
• For map levels, have a trigger_multiple with only Regen() at the start. Call ResetTouched() on the fail trigger_teleport. Keep in mind that while this works fine during map runs, if the player is using save/teleport commands (e.g. for practice), they may teleport themselves back to the beginning of the jump before they touch the fail trigger. The player's list of touch triggers would therefore not be reset, and any Regen() triggers during the jump would fail to work. If you think this will be a problem for your level (e.g. high chance that people will want to practice the jump with save/tele commands + long fall times to hit fail teleport), consider using the first method or switch to using projectile limit triggers instead.
• For bonuses, have a ResetTouched() trigger at the start of the bonus, and have Regen() on the fail teleport trigger. If you teleport to the bonus through a tele door, add Regen() to that door too. On Tempus, for example, sm_r regenerates the player so even if a player resets before touching the Regen() fail trigger, they will still receive full ammo when starting the bonus.
• Make sure to add a ResetTouched() trigger at the start zone of your map, so that resetting (sm_r on Tempus) will also clear the list of any touched triggers during the previous map run.

Advanced usage:
You can filter by class directly with the Regen() function by giving it an optional class argument. This offers a more convenient way of filtering by class (rather than creating a separate filter_tf_class entity). The class specified is the class that will exclusively be regenerated.

Examples of valid output parameters include (case sensitive):

• Regen(solly) or Regen(soldier)
• Regen(demo) or Regen(demoman)
• Regen(pyro)
• etc.

A full list of valid class arguments can be found here.

2. Projectile Limit Regen

Inspired by Momentum Mod's (proposed) system for dealing with limited regen, projectile limit regen allows you to give the player X number of projectiles to complete a jump, for any soldier or demoman primary/secondary weapon. In this limited state, reloading is blocked and once reaching 0 clip ammo, the weapon turns translucent and becomes unusable until more ammo is given or the weapon is reset. All rocket launchers are supported, including the Cow Mangler and Beggar's Bazooka (both in its unmodified form, and when it is modified to function like stock). You can also limit shotgun/Righteous Bison ammo. All demoman sticky launchers are supported as well as primary grenade launchers.

Projectile limit regen offers:

• Opportunity for novel jump ideas (e.g. creating levels/bonuses that require careful resourcefulness of a specific amount of ammo, fine control when forcing a jump to be completed in a maximum number of rockets, etc.)
• Ability to create a 1:1 experience with a Momentum Mod map port for limited regen jumps
• Optional, built-in anti-cheat to prevent a jump being completed in more than the specified limit amount (i.e. with "destroy" triggers: see Usage section)

Usage:

Spoiler (click to show/hide)

First, download the latest regen.nut file and place it in your Team Fortress 2/tf/scripts/vscripts folder. Then create a logic_script entity somewhere in your map:

• In the logic_script object properties, set "Entity Scripts" to regen.nut (do not use "Manage..." button, it is broken)
• Give the logic_script entity a name (e.g. "regen")

Simple limited regen includes the following functions for you to use in Hammer:

• RocketLimit(amount) - Sets limit of X rocket projectiles (e.g. RocketLimit(7) = limits to 7 rockets)
• ShotgunLimit(amount) - Sets limit of X shotgun/bison shots (e.g. ShotgunLimit (2) = limits to 2 shots)
• PipeLimit(amount) - Sets limit of X pipe projectiles (e.g. PipeLimit (1) = limits to 1 pipe)
• StickyLimit(amount) - Sets limit of X sticky projectiles (e.g. PipeLimit (0) = sticky launcher is purposefully disabled but still equipable)
• LeaveLimit() - Tracks when a player leaves a limit trigger. You must use this function with an OnEndTouch output any time you use one of the limit functions (e.g. RocketLimit, StickyLimit).
• ResetLimit() - Resets the limit state of all weapons equipped by the player, but does not regenerate their ammo in the process.
• ResetTouched() - Like simple limited regen, this function resets the list of triggers that the player has touched, allowing previously touched limit triggers work again. See "Recommended Guidelines" section to understand when you need to use this function.

Using func_regenerate/Regen() or anything that regenerates the player resets weapons back to their normal, pre-limit state. Hence, do not use func_regenerate during a jump that uses limit functions - only use it, for example, at the end of the jump when you want to reset the weapons back to their normal state for subsequent levels. The ResetLimit() function should only be used when you want to reset weapons back to normal but do not want to regenerate their ammo during the process (see this part of the demonstration video for func_regenerate resetting a weapon's limit state, and this part for an example of ResetLimit() being used).

You can limit ammo to any amount between 0 and 254. You can intentionally limit a weapon to 0 ammo to disable it.

Recommended Guidelines:
Like simple limited regen functions, limit triggers protect against lingering in and out of a trigger by only allowing each trigger to set an ammo limit once per attempt at a level. ResetTouched() must be called to make limit trigger(s) work again for the level. For the best compatibility with Tempus or any servers using plugins, I recommend the following guidelines:

• For most cases, have a trigger_multiple at the start of your jump that contains limit function(s) and ResetTouched() simultaneously. For any subsequent limit function(s) used in the level, do not use ResetTouched() on those triggers. For Tempus compatibility, you must use this method for the start of bonuses or if you are using limit triggers on the first level of your map. Use the "destroy" option if you want to anti-cheat against using more than the intended projectiles (e.g. pre-placing stickies or telesyncing/prefiring rockets).
• If you want to ensure the player only has their ammo limited once at the start of a jump, and cannot re-enter the start trigger to regain ammo, then I recommend the following:
• For map levels (excluding level 1), have a trigger_multiple with only your desired limit function(s). Call ResetTouched() on the fail trigger_teleport. Keep in mind that while this works fine during map runs, if a player is practicing and teleports back to the start of the level before touching the fail teleport trigger, the limit triggers will not reset. The first method does not have this problem, so consider using that instead (potentially with the "destroy" option).
• If you have any limit triggers that can only be touched once per attempt before being reset, make sure to add a ResetTouched() trigger at the start zone of your map, so that resetting (sm_r on Tempus) will also clear the list of any touched triggers during the previous map run.

"destroy" Limit Trigger Option:
Each of the limit functions (RocketLimit, ShotgunLimit, PipeLimit and StickyLimit) has an optional argument "destroy" (e.g. RocketLimit(6, destroy) or StickyLimit(12, destroy)). "destroy" limit triggers do not get added to the player's list of touched triggers. As such, a player will have their ammo limited every time they enter a "destroy" trigger. However, the bigger difference is that it has the following anti-cheating effects:

• Leaving the limit trigger and re-entering will destroy any active projectiles (e.g. rockets or stickies that have been placed). This prevents rocket telesyncs or pre-placing stickies.
• If the players speed is above a certain threshold when entering the trigger, velocity will be reset. This prevents, for example, building a lot of speed going into the jump to cheese it (e.g. triple pre before entering the trigger).

It's up to you when you want to use this option, but it best suits map levels without connectors (i.e. tele doors), and the start of bonuses/levels where you want to ensure your desired ammo limit isn't easily cheated.

Steps for adding projectile limit functions to triggers:
- Create a trigger_multiple brush entity. When using any limit funtions, you MUST start by adding LeaveLimit() OnEndTouch to prevent potential bugs:
    1. Open the trigger_multiple's object properties window
    2. Go to the Outputs tab
    3. Create an "OnEndTouch" output:
        - Target Entity = regen (or whatever you named your logic_script entity)
        - Target Input = RunScriptCode
        - Parameter = LeaveLimit()
- Now add any desired limit function, e.g.:
    1. Stay on the Outputs tab
    2. Create an "OnStartTouch" output:
        - Target Entity = regen (or whatever you named your logic_script entity)
        - Target Input = RunScriptCode
        - Parameter = RocketLimit(6)
- Now, for example, you might want to add ResetTouched() to the same trigger, e.g.:
    1. Stay on the Outputs tab
    2. Create an "OnStartTouch" output:
        - Target Entity = regen (or whatever you named your logic_script entity)
        - Target Input = RunScriptCode
        - Parameter = ResetTouched()

3. func_regenerate Re-implementation

A VScript re-implementation of a func_regenerate trigger, made by ficool2 with some modifications.

Typical func_regenerate triggers cannot be filtered by class (or any other filter entity). Since this func_regenerate re-implementation runs on trigger_multiple triggers instead, filtering is supported. Furthermore, for added convenience, you can filter regen by supplying an optional class type when calling the main FuncRegen function. This would allow you to, for example, cover the entire map in a trigger_multiple for unlimited demoman regen, but have limited regen for soldier jumps in your map. Prior to VScript, doing something like that was not possible and only achievable with plugins (e.g. +regen on Tempus).

Usage:

Spoiler (click to show/hide)

First, download the latest regen.nut file and place it in your Team Fortress 2/tf/scripts/vscripts folder. Then create a logic_script entity somewhere in your map:

• In the logic_script object properties, set "Entity Scripts" to regen.nut (do not use "Manage..." button, it is broken)
• Give the logic_script entity a name (e.g. "regen")

This func_regenerate re-implementation includes 2 functions for you to use in Hammer:

• FuncRegenStart() - Registers when a player starts touching the trigger_multiple trigger. You can supply an optional class argument to only allow that particular class to be regenerated (e.g. FuncRegenStart(soldier) or FuncRegenStart(demoman)). A full list of valid class arguments can be found here.
• FuncRegenEnd() - Registers when a player leaves a FuncRegen trigger. You must use an OnEndTouch output for this function.

Steps for adding func_regenerate re-implementation functions to triggers:
- Create a trigger_multiple brush entity
    1. Go to the Outputs tab
    2. Create an "OnStartTouch" output:
        - Target Entity = regen (or whatever you named your logic_script entity)
        - Target Input = RunScriptCode
        - Parameter = FuncRegenStart()
- Now add the function to register when a player leaves a FuncRegen trigger:
    1. Stay on the Outputs tab
    2. Create an "OnEndTouch" output:
        - Target Entity = regen (or whatever you named your logic_script entity)
        - Target Input = RunScriptCode
        - Parameter = FuncRegenEnd()

Normal func_regenerate triggers have an "Associated Model" field so that models with open/close animations happen when the trigger is touched (e.g. typically a resupply cabinet). While trigger_multiple triggers don't have this field, you can spoof it with a "damagefilter" key:
-   Have a model in your map with open/close animations such as a resupply cabinet. Make sure to give your prop a name.
-   Open the object properties for your trigger_multiple entity
    1.   Go to the Class Info tab
    2.   Turn off SmartEdit so that you can add your own key/value pairs.
    3.    Add a new key/value pair with the key name "damagefilter" and the value as the name of your prop.

Your model's animations will now work when a player touches the FuncRegen trigger.

Miscellaneous: Useful Functions

These are standalone versions of functions that are used within the script that you may find useful. They include:

• DestroySoldierProjectiles() - Destroys all soldier projectiles. This function is used by "destroy" limit triggers but you may find it useful outside of that context. E.g. use on your level's fail trigger_teleport to prevent telesyncs. Projectiles are destroyed on the server frame after this function is called. Add KillVelocity() to your trigger if you want to prevent the player from being able to receive knockback during that very small window (e.g. if the telesync rocket(s) hit the player at the same time as being teleported to the start of the level).
  
• DestroyDemomanProjectiles() - Destroys all demoman projectiles. This function is used by "destroy" limit triggers but you may find it useful outside of that context. Projectiles are destroyed on the server frame after this function is called. In some cases, you will want to add KillVelocity() to your trigger to prevent the player from receiving sticky/pipe knockback during that very small window.
  
• KillVelocity() - kills all player velocity. It also accepts an optional class argument so that it will only kill velocity for a certain class (e.g. KillVelocity(soldier) or KillVelocity(demoman)). E.g. you can use this on trigger_teleports (tele doors, fail triggers) to prevent telehops. This offers a convenient alternative to creating trigger_catapult entities.
  
• KillVelocityEx() - An "extended" version of KillVelocity() that only kills the player's velocity when their X/Y velocity exceeds walk speed + 30 units, and only cancels Z velocity when it is greater than initial jump speed (277u/s). This is the logic used by "destroy" limit trigger anti-cheat. You can use this function along with DestroySoldierProjectiles() or DestroyDemomanProjectiles() to re-create "destroy" anti-cheat on a separate trigger_multiple. Like KillVelocity(), it also supports the optional class argument (e.g. KillVelocityEx(soldier)).

Usage:

Spoiler (click to show/hide)

First, download the latest regen.nut file and place it in your Team Fortress 2/tf/scripts/vscripts folder. Then create a logic_script entity somewhere in your map:

• In the logic_script object properties, set "Entity Scripts" to regen.nut (do not use "Manage..." button, it is broken)
• Give the logic_script entity a name (e.g. "regen")

Steps for adding a wrapper function to triggers:
- Create a trigger brush entity (or an any existing trigger entity, e.g. trigger_teleport)
    1. Go to the Outputs tab
    2. Create an "OnStartTouch" output:
        - Target Entity = regen (or whatever you named your logic_script entity)
        - Target Input = RunScriptCode
        - Parameter = e.g. KillVelocity()

[879m]

setting a players ammo has never been simpler!