OnCatapultFireForce
OnCatapultFireForce is called inside Catapult.Fire right before the projectile is launched, and the returned float replaces the game's force multiplier.
object OnCatapultFireForce(Catapult catapult, BasePlayer shooter, float force)Parameters
| Parameter | Type | Description |
|---|---|---|
catapult | Catapult | The Catapult entity that is about to fire. Use it for its transform, passenger list and owner checks. |
shooter | BasePlayer | The BasePlayer operating the catapult. May be null when the catapult is fired without a player on it, so always null-check. |
force | float | The launch force multiplier the game computed from the pull amount, typically between 0.5 and 1. Return a different float to replace it. |
Return value
Return null (or any non-float) to keep the game's computed force unchanged. Return a float to replace the force multiplier used for this shot; the server uses that value directly.
How it works
The hook fires in Catapult.Fire after the game has converted the pull/release amount into a force scale through two Mathf.Lerp calls. That computed value (roughly 0.5 at minimum pull up to 1.0 at full pull) is passed as force together with the firing Catapult and its shooter. Only the force value is used: if you return a float, the game stores it back into its local variable and uses it for the shot, so the projectile flies farther or shorter than normal.
Because shooter is whatever player the catapult resolves as its operator, it can be null for unmanned or scripted launches. Check it before using permission or player data. The catapult argument lets you read the entity's position or owner. You cannot declare a narrower type for the catapult or shooter to filter calls, since there is only one call site and both arguments are always those types.
Practical uses are tuning siege balance: scaling force by permission group, limiting range on PvE servers, or blocking a launch entirely. There is no way to cancel the firing from this hook, only to change the force value.
Example plugin: Boost catapult force for a permission group
using System;
using System.Collections.Generic;
using Newtonsoft.Json;
using Oxide.Core;
using UnityEngine;
namespace Oxide.Plugins
{
[Info("Catapult Force Boost", "RustPluginGenerator", "1.0.0")]
[Description("Scales catapult launch force for players with a permission")]
public class CatapultForceBoost : RustPlugin
{
private const string PermBoost = "catapultforceboost.boost";
private PluginConfig config;
private readonly Dictionary<ulong, float> lastLaunch = new Dictionary<ulong, float>();
private class PluginConfig
{
[JsonProperty("Force multiplier")]
public float Multiplier { get; set; } = 1.4f;
[JsonProperty("Maximum force")]
public float MaxForce { get; set; } = 1.5f;
[JsonProperty("Cooldown seconds per player")]
public float Cooldown { get; set; } = 3f;
}
protected override void LoadDefaultConfig() => config = new PluginConfig();
protected override void LoadConfig()
{
base.LoadConfig();
try
{
config = Config.ReadObject<PluginConfig>();
if (config == null) throw new Exception();
}
catch
{
PrintWarning("Configuration file is invalid, using defaults");
LoadDefaultConfig();
}
SaveConfig();
}
protected override void SaveConfig() => Config.WriteObject(config);
protected override void LoadDefaultMessages()
{
lang.RegisterMessages(new Dictionary<string, string>
{
["Boosted"] = "Catapult force boosted to {0:0.00}"
}, this);
}
private string Msg(string key, string userId = null, params object[] args) =>
string.Format(lang.GetMessage(key, this, userId), args);
private void Init()
{
permission.RegisterPermission(PermBoost, this);
}
private object OnCatapultFireForce(Catapult catapult, BasePlayer shooter, float force)
{
if (catapult == null || shooter == null) return null;
if (!permission.UserHasPermission(shooter.UserIDString, PermBoost)) return null;
ulong id = shooter.userID.Get();
float now = UnityEngine.Time.realtimeSinceStartup;
if (lastLaunch.TryGetValue(id, out float previous) && now - previous < config.Cooldown)
return null;
lastLaunch[id] = now;
float boosted = Mathf.Clamp(force * config.Multiplier, 0.1f, config.MaxForce);
shooter.ChatMessage(Msg("Boosted", shooter.UserIDString, boosted));
return boosted;
}
private void Unload()
{
lastLaunch.Clear();
}
}
}The plugin registers a permission that lets chosen players get more range out of a catapult. In OnCatapultFireForce it checks that a real player is firing, verifies the permission through permission.UserHasPermission, and reads a configurable multiplier. When the player has the permission the hook multiplies the incoming force by the config value and clamps it to a sane maximum so shots stay within the map. Players without the permission get null back, so the game keeps its own value. Every boosted launch is rate-limited per player via a short cooldown dictionary, and the cooldown is pruned on plugin unload.
Common use cases
Range gating on PvE servers
Clamp the returned force to a small value so catapults cannot reach distant bases, or return the original value for staff only.
VIP siege bonus
Multiply force for a permission group so donors get noticeably longer shots without touching the projectile itself.
Admin diagnostics
Compare the incoming force with the shooter's pull history by storing the last few values per player and adjusting outliers.
Pitfalls
shooter can be null
Unmanned or scripted catapults may fire without a player reference, so null-check before reading permissions or user IDs.
No cancellation
The hook only replaces the force value; returning null does not stop the shot. To block firing you need a different approach such as removing ammo beforehand.
Extreme force values
Returning a very large float can send the projectile off-map or through geometry. Clamp with Mathf.Clamp before returning.
Build a plugin with OnCatapultFireForce
Describe what should happen and get a compiled plugin that uses this hook.
Edit the prompt on the next screen. 2 free plugins a month, no card.
Last updated Oct 26, 2026. Found a mistake? Email support@rustplugingenerator.com.
Build a plugin with OnCatapultFireForce
Generate