Description

Grappling Hook

Questions? Support? Join the discord: https://discord.nikhub.dev

This plugin introduces a new tool – the Grappling Hook. Equip it, aim it, shoot it and let the fun literally pull you in! Time your balancing, swinging and grappling perfectly to cover massive distances quickly, confuse your enemies, climb cliffs or tall structures or to perform a literal raid from above. And yes, you can totally use your weapons when swinging. High risk, high reward: the plugin utilises native, lightweight physics based on real life. When you’re swinging, your body is completely at the mercy of your skill…. and the law of gravity itself! Crashing at high speeds CAN be lethal. Straight-forward to configure, super easy to learn, challenging to master and incredibly fun to use!

The most fun and liberating “mode of transport” to date

It cannot be described how intuitive, smooth and satisfying it feels to swing with Grappling Hooks in Rust. It’s one of those things you have to try for yourself. And after you do, you will never want to go back to boring old walking – or even admin flying! You have been warned! And forget everything you know about Rust vehicles – apart from the fact that you can totally grapple onto them, too!

There’s practically no overhead associated with Grappling Hook. All the heavy lifting is handled with native Unity and Rust physics and components just the way they COULD BE used in the Vanilla version – if only Facepunch were not so busy with drones and Twitch drops! So rest assured, server owners, this won’t noticably affect your server/client FPS or cause any lag (if you stick with recommended settings!)

GRAPPLE: FIRE3 BUTTON (usually: MIDDLE MOUSE) AND/OR BINDABLE F1 COMMAND: “grapple”

If you’re aiming at a point  that’s close enough to you (closer than the maximum rope length) while you have a Grappling Hook equipped in your belt (it doesn’t have to be an active item, just in your belt), you will grapple on to that point. It can be anything the admin allows – terrain, vehicles, buildings, deployables, trees etc. It usually takes a bit for the grappling projectile to arrive to its target point (based on the configurable projectile velocity), but once it does, you will know – and everyone else around you or the target point will know too, thanks to a highly visible trail of snowballs (which is the only feasible way of displaing the rope without killing performance) and tactile feedback effects! When you’re grappled, you can reel in, reel out and release to control your swinging.

REEL IN: SPRINT (usually: SHIFT)

This will shorten the the rope, pulling you closer to the target point. Tap it lightly (but repeatedly) for a slower ascend or hold it for that Hail Mary, full-force lunge towards the target point.

REEL OUT: DUCK (usually: CTRL)

This will lengthen the rope (until the rope reaches maximum length defined in the config), allowing you to move further from the target point. Tap it lightly, otherwise you’ll fall down quickly! If you’re hanging, useful for graceful descents down heights.

RELEASE: JUMP (usually: SPACE)

When you’re grappled, you will want to let go at some point. Pressing the JUMP key will do that and you will start freefalling/rolling down a hill. Releasing also happens every time you shoot a new grappling projectile (and if the config specifies it, also when you take impact damage and/or when you’re shot/attacked by other players). When you release and then land on terrain (or anything else you can land on), you will go back to the normal state (walking/running/jumping) as soon as you slow down enough and stop rotating.

BODY ROTATION: MOUSE MOVEMENT

When you’re in an inert state (you’re grappled or you’re freefalling from a grapple), you can rotate your whole body towards where you’re looking at, including twists, flips, tumbles and the like. Just aim at the direction you you want to rotate your body to and it will gradually follow there. Keep your mouse centered to minimise movement/stop rotating! If you’re skilled enough, you can easily orient your body so you’re hanging upside down, or you can fly sideways. It takes some using too, but once you get the hang of it, you will be able to perform amazing tricks and jumps! Rotating your body also shifts your body weight (just imagine the centre of your mass is 2m “below” your feet – depending on which direction you’re looking at) and with some practice you can use it to swing on the rope like a pendulum and give it some momentum.

Admin chat commands (must be ownerid/moderatorid or have grapplinghook.admin perm)

/givehook [optionally: player name]
This will give you or the player of your choice 1 grappling hook item – use this first if you want to define kits or sale offers! It will be automatically put in your container belt and you should be good to go.

Permissions (Oxide.Grant user YourName [permission name starting with grapplinghook.]

Admins and VIPs don’t have to follow the rules you have set out in the config! Thanks to these permissions, which can be applied to individual users/groups, YOU decide who gets to use what features in what way! Great VIP incentive!

grapplinghook.use
If you want to allow only select players to use Grappling Hooks (see Config), this is the permission they need. Otherwise it can be ignored.

grapplinghook.admin
This permission is used for the /givehook and /gh_cfg commands. Owners/moderators on the server won’t need it.

grapplinghook.everywhere
This permission allows the player to grapple even if they’re in a Safe Zone (if your config forbids it), building blocked zones (again, according to config) or in a blacklisted Zone Manager zones (that you also get to define).

grapplinghook.ignore_blocks
This permission allows the player to bypass checks for Raid Block/Combat Block before beling allowed to grapple (if you use the No Escape plugin and have decided you want to utilise in the config)

grapplinghook.infinite_use
This permission won’t damage the Grappling Hooks durability when a player with the perm uses them, effectively allowing for infinite usage.

grapplinghook.infinite_length
Players that have this permission can grapple as far away as they want (rope length is effectively infinite). WARNING: Don’t give it to regular players. The physics might start getting unpredictable at massive rope lenghts.

grapplinghook.no_cooldown
Players with this permission can grapple as often as they want, ignoring the cooldown. WARNING: Don’t give it to regular players, this is one of the only scenarios a lag could be induced by spamming rope close and often.

grapplinghook.instant_projectile
When a player with this permission shoots a grappling projectile, it will arrive at target point and grapple the player instantly, with no time passed between shooting and grappling. If you want this for all players, it’s better to just set the projectile velocity to 0, it will have the same effect.

grapplinghook.no_damage_on_impact
For players not in god mode, who crash into things, having this permission will completely nullify all damage taken from impact. If you’re running a build server and want to achieve the same effect for all players, it’s better to disable impact damage in the config instead.

grapplinghook.no_ungrapple_on_attacked
If your settings cause attacked players to forcibly release from the grapple, having this permission will negate the effect and the player will take the damage, but stay on the rope.

grapplinghook.no_unpgrapple_on_impact
If you have enabled damage from impacts (and the player with this permission doesn’t have the no damage on impact permission), players with this permission won’t forcibly release.

grapplinghook.silent_grappling
Having this permission will not produce any effects that are audible/visible to other players, so they can grapple freely without alerting anyone to their presence (at least those who can’t see them, but who could potentially hear them).

grapplinghook.impact_damage_in_chat
Mainly intended as a debug permission for admins to see how much damage was taken during an impact (so you can play around and decide on the lethal joules, damage treshold and human body weight, they all play part in calculating impact damage). But you can give it to normal players too – whenever a holder of this permission takes impact damage exceeding your set treshold, they will see a detailed message

grapplinghook.instant_dismount
Originally intended as a debug permission for admins, it looks like it could also have some OP tactical advantages. After a player with this permission presses JUMP, again, after ungrappling, they will instantly bail even mid air, going back to the “falling downwards” state as if the player just dismounted from a minicopter mid-air. Ssame thing would normally happen if the player landed in water or their velocity fell below the configurable treshold. WARNING: If you decide to give this permission to normal players, keep in mind that it’s not very difficult to abuse it and instantly come to a stop before hitting a wall/ground, no matter how fast they’re going. Based on how well they time their bails, they might not even take any fall damage. Depending on how you look at it, it’s either a useful permission for admins or something that you want as a part of your gameplay. Up to you! There’s no judgement on Lone.design!

Configuration (oxide/config/GrapplingHook.json and chat commands)

Although nothing stops you from editing the JSON file by hand, there’s a better solution available – and you won’t even have to reload your plugin afterwards.

In order to run any of the config commands, you will need to have ownerid or moderatorid (or the grapplinghook.admin permission).

If you want to prevent players without the grapplinghook.everywhere permission from being able to grapple to certain things, use the command below to add/remove prefab shortnames from the blacklist. By default, the following are blacklisted: Supply Drop, Cargo Plane, Chinook helicopter, Bradley APC, Patrol Helicopter, Cargo Ship.

/gh_blacklist_shortname add [prefab shortname]
Adds a prefab shortname to the blacklist, meaning that grappling to that prefab will be disabled from now on. If the prefab already exists in the blacklist, it will tell you. Make sure you spell the prefab properly, as the plugin doesn’t check for validity.

/gh_blacklist_shortname remove [prefab shortname]
Removes an existing prefab shortname from the blacklist, meaning that grappling to that prefab will be enabled from now on. If the prefab doesn’t exist in the blacklist, it will tell you.

Likewise – if there’s any Zone Manager zones that you don’t want the players without grapplinghook.everywhere permission to grapple inside, there’s a similar command for Zones:

/gh_blacklist_zone add [Zone Manager Zone ID]
Adds a zone ID to the blacklist, meaning that grappling in that zone will be disabled from now on. If the zone already exists in the blacklist, it will tell you. This doesn’t check if a zone actually exists in Zone Manager at the moment, you can define it any time.

/gh_blacklist_zone remove [Zone Manager Zone ID]
Removes an existing zone ID from the blacklist, meaning that grappling in that zone will be enabled from now on. If the zone doesn’t exist in the blacklist, it will tell you.

And here’s the rest of the config options. Type /gh_cfg in the chat. If you’re a server owner/moderator or have the grapplinghook.admin permission, you should see a rundown of all settings (and what values they currently have) and what to type to change them. Here’s a default configuration as of version 1.0.0. If you type /gh_cfg [configValue] with no parameters, it will tell you detailed information about the setting – what it does, what types of values it expects and the upper and lower limits of those (if applicable). You can change any setting you like at any time and all changes will be applied instantly, so feel free to experiment with the ones that suit your server best.

/gh_cfg grapplingRequiresPerm [logical values (true or false)]
If true, players without grapplinghook.use permission won’t be able to use the Grappling Hook

/gh_cfg grapplingEnableFire3 [logical values (true or false)]
If true, players will be able to grapple using ;FIRE3 (usually middle mouse button)

/gh_cfg grapplingEnableCommand [logical values (true or false)]
If true, players will be able to grapple using the grapple console command (which can be bound to any key)

/gh_cfg grapplingBuildingBlocked [logical values (true or false)]
If true, players will be able to use the grappling hook even when building blocked

/gh_cfg grapplingSafeZone [logical values (true or false)]
If true, players will be able to use the grappling hook even when they’re in a safe zone

/gh_cfg grapplingCooldown [fractions (like 1.2345) between 0 and 10000]
This is how often (in seconds) players without grapplinghook.no_cooldown permission will be able to shoot the hook

/gh_cfg grapplingItemUses [integers (like 12345) between 1 and 1000000]
This is many times the Grappling Hook can be used before the item breaks (unless the player has the ;grapplinghook.infinite_use permission)

/gh_cfg projectileIsInstant [logical values (true or false)]
If true, players without the ;grapplinghook.instant_projectile will be grappled to the valid point you’re looking at instantly without waiting for the projectile to arrive there (ignores projectile velocity)

/gh_cfg projectileVelocity [fractions (like 1.2345) between 0 and 10000]
How fast (in meters per second) the projectile will travel to the target point for players without the ;grapplinghook.instant_projectile perm

/gh_cfg projectileItemID [integers (like 12345) between -2147483648 and 2147483647]
The ID of the projectile item (can be any dropped item)

/gh_cfg projectileSkinID [integers (like 12345) between 0 and 18446744073709600000]
The skin ID of the projectile (the long number in the Steam workshop URL)

/gh_cfg projectileRotX [fractions (like 1.2345) between -360 and 360]
Projectile’s visual rotation correction X (Euler angles)

/gh_cfg projectileRotY [fractions (like 1.2345) between -360 and 360]
Projectile’s visual rotation correction Y (Euler angles)

/gh_cfg projectileRotZ [fractions (like 1.2345) between -360 and 360]
Projectile’s visual rotation correction Z (Euler angles)

/gh_cfg ropeMaxLength [fractions (like 1.2345) between 0 and Infinity]
The maximum length of a rope (in meters) for players without ;grapplinghook.infinite_length. Setting values higher than several hundred might cause some wacky physics to happen.

/gh_cfg ropeSpringForce [fractions (like 1.2345) between 0 and Infinity]
The stronger the force (in Newtons), the stiffer and less elastic the rope is

/gh_cfg ropeSpringDamper [fractions (like 1.2345) between 0 and Infinity]
The more damping (in Newtons), the smoother and less springy the rope is

/gh_cfg ropeReelAccelerate [fractions (like 1.2345) between 0 and 10]
How fast the reeling speed builds up/dies down. Larger values combined with smaller max speed values allow for less responsive, but tighter-feeling reeling controls

/gh_cfg ropeReelMaxSpeed [fractions (like 1.2345) between 0 and Infinity]
The maximum reeling speed. Limiting it to lower values is the main factor of making sure players rely on good swinging/pendulum action for airtime as opposed to speed boosts just from reeling action.

/gh_cfg ropeReelVisualSpeed [fractions (like 1.2345) between 0 and 1]
When reeling in/out, the larger this value is, the faster the rope segments appear to go up/down. Setting it to 0 effectively freezes reeling animation.

/gh_cfg ropeSegmentCount [integers (like 12345) between 1 and 50]
How many rope segments are animated between the projectile target and the player. Reducing/increasing this number might slightly improve the rope performance/visuals, respectively

/gh_cfg damageTakeOnImpact [logical values (true or false)]
If true, players who are swinging or falling from a grapple will take damage when they collide with their surroundings. The damage is calculated based on the impact velocity, relative impact angle, the human body mass and the lethal impact force, then applied after subtracting the damage treshold. The former 2 are based on the physical state, the latter 3 are configurable.

/gh_cfg damageEffectOnImpact [logical values (true or false)]
If true, a random effect from a pre-defined palette will be played for fun when players get hurt from the impact

/gh_cfg damageImpactUngrapples [logical values (true or false)]
If true, the damage from the impact will automatically cause the grappled player to lose grip and ungrapple

/gh_cfg damagePVPUngrapples [logical values (true or false)]
If true, the damage from PVP (including NPCs) will automatically cause the grappled player to lose grip and ungrapple

/gh_cfg damageCooldown [fractions (like 1.2345) between 0 and 10000]
This is how often (in seconds) players will register impact damage. Set it to higher values for players to take more time between damage hits.

/gh_cfg damageHumanBodyMass [fractions (like 1.2345) between 0 and 1000]
Increasing this number (in kilograms) will make the damage curve steeper (it’s meant to be multiplied by squared relative velocity of the impact, and the halved result is the kilojoules of the impact)

/gh_cfg damageHealthJoules [fractions (like 1.2345) between 0 and Infinity]
This number (in joules) is the equivalent of receiving 100 HP of damage from impact. Set it to higher values to significantly reduce the amount of damage taken from impact.

/gh_cfg damageTreshold [fractions (like 1.2345) between 0 and Infinity]
This number can offset the curve, so the larger it is, the steeper the curve gets the more damage you get, starting from 0 damage. Any damage below this value will be ignored as impact damage.

/gh_cfg dismountWaterFactorTreshold [fractions (like 1.2345) between 0 and 1]
How submerged the player has to be in order to be automatically returned to non-inert state (back to walking). 0 means not even the toes, 1 means head completely covered. Set it to higher values to ignore what appeares to be merely grazing the surface of the water.

/gh_cfg dismountVelocityTreshold [fractions (like 1.2345) between 0 and 1]
When the velocity of a player in an inert state (as in, non-walking) falls below this value (in meters per sec), the player automatically returns to walking (or falling, if mid-air) state. Set to higher values to wait less time for the player to slow down before they go back to normal physics.

/gh_cfg checkEscapeBlock [logical values (true or false)]
If true, Combat Blocked/Raid blocked players won’t be able to grapple. This overrides checkCombatBlock and checkRaidBlock settings, meaning only 1 CallHook is done instead or 2 (better performance). Requires No Escape plugin.

/gh_cfg checkCombatBlock [logical values (true or false)]
If true, Combat Blocked players won’t be able to grapple. Requires No Escape plugin. If checkRaidBlock is also true, it’s not recommended to set checkEscapeBlock to false – since you want both, it’s better to perform 1 CallHook instead of 2.

/gh_cfg checkRaidBlock [logical values (true or false)]
If true, Raid Blocked players won’t be able to grapple. Requires No Escape plugin. If checkCombatBlock is also true, it’s not recommended to set checkEscapeBlock to false – since you want both, it’s better to perform 1 CallHook instead of 2.

Translation support (oxide/lang/en/GrapplingHook.json)

I have learned my lesson. And the lesson was, not everyone had lessons in English, Rust is a game for players all over the world! Nobody likes editing the plugin to change the text, so I’ve included all strings (apart from config, but that’s just for admins) dumped to a language file that can be quickly edited, so you can give your server that extra personal touch.

Many ways of obtaining the item: Server Rewards, various loot managers, Kits

Owners/moderators/players with grapplinghook.admin permission can type /givehook in the chat to get the item quickly. If you specify a player name (after space) as an argument, it will be given to that player instead.

Although you can’t really make it craftable through vanilla mechanics, there exist free plugins to remedy that. There’s Server Rewards, where you can sell the item in the shop.You can try Alpha Loot / Better Loot to make it spawn in loot containers in the wild. Or you can put the Grappling Hook item inside of Kits.

For all those and other plugins, a valid Grappling Hook item is any Handmade Fishing Rod (ID: 1569882109, shortname: fishingrod.handmade) with the skin ID 2387182643

Fishing rods are not normally used in game and they serve no purpose – apart from looking cool holstered on someone else’s back!

Works with No Escape (Raid/Combat Block) and Zone Manager

Maybe you want to make sure grappling cannot be used to escape sticky situations. Or maybe you don’t want players to use their cool new toy in certain zones and you’d like to blacklist them. In any case, you’re covered! Support for more plugins will be considered on a per-request basis – just let me know what else could be taken into account!

EULA

I’m not going to speak legalese here. It’s going to be short and to the point. By purchasing Grappling Hook you hereby agree to these conditions:

• If something goes wrong with your server (not that it will!) while using this plugin, you will not hold Nikedemos responsible. You use the plugin at your own risk. Always make sure you make backup copies before experimenting with anything.
• You are granted a license to use the plugin on up to 6 servers at time. You have to be the owner or co-owner of those servers. This license will never expire. When the plugin gets updated, every license owner is entitled to an update.
• You will not distribute this plugin in any shape or form – not on forums, social media, not to your friends, not to other server owners nor other plugin developers. Making plugins takes time and effort and I really appreciate respecting plugin developers by not stealing their work. The only way to legally own and use Grappling Hook on a server you own is to purchase a license. If you’re not a permanent co-owner on a particular server (that has been participating in the server costs/revenue), you can’t deploy the plugin there, even if you’re friends with the owner. They have to purchase a separate license.