Mod Hooks Reference

Intermediate40-60 minutesWindowsNotepad++Unity Editor

Mod Hooks are script components that can be added to GameObjects in Unity and exported in asset bundles, provided they match a script in the base game code. They are the officially supported mechanism for attaching custom behavior to mod content without requiring server-side scripting or C# plugin development. A Mod Hook is a Unity MonoBehaviour script that exposes events (UnityEvent fields in the Inspector) which the mod author can wire to other component properties: toggling visibility, playing an animation, spawning an effect, broadcasting a chat message, triggering an airdrop, or driving any other component action that Unity's event system supports.

The Mod Hooks system was originally proposed and coined by VitaxaRusModding and was incorporated into the official Unturned™ toolchain following community discussion on the game's GitHub issue tracker. The scripts are imported into a mod developer's Unity project from the Project.unitypackage, and they appear under the Unturned components menu in the Unity Editor after import. Each script documents its purpose and members within its *.cs source file in the base game code, and the official Smartly Dressed Games documentation provides a high-level summary of every hook type in Chapter 12 of the modding documentation. This article is the 57 Studios™ canonical reference for every Mod Hook type in the current game version, organized by category, with parameters, use cases, event wiring guidance, server-versus-client behavior notes, and validated hook combination patterns for each type.

The Mod Hooks system spans thirty-six distinct hook scripts as of the current game version: twenty-one event listeners that respond to game-world conditions, nine event instigators that let the prefab drive game-world actions, and six miscellaneous utility hooks that provide specialized functionality including crafting tag management, fall damage overrides, barricade destruction, audio routing, and event repetition. Each hook is documented individually in the sections that follow, and a comprehensive reference table at the end of the article maps every hook to its trigger condition, authority context, and primary use case.

Documentation source: This article documents the Mod Hooks system as published in the official Smartly Dressed Games modding documentation, Chapter 12 (Mod Hooks). The hook system is actively maintained and may receive new hook types in future game updates; consult the official documentation for hooks added after this article's publication date. The original proposal for the Mod Hooks system by VitaxaRusModding is referenced in the official documentation.

Who this article is for

This article is written for Unturned™ mod developers who work in the Unity Editor and want to attach custom behavior to mod GameObjects without writing C# code. If you only author .dat files and do not work with Unity prefabs, Mod Hooks are not relevant to your workflow. However, any mod developer who ships custom prefabs in asset bundles -- whether for items, vehicles, map objects, or NPC interactions -- will benefit from understanding which hooks are available, what events they fire, how to wire those events to drive component behavior in the built game, and which authority context (server versus client) each hook operates in. The authority context distinction is particularly important for multiplayer mods, because a hook that functions correctly in singleplayer testing may fail to produce the expected behavior for other players on a dedicated server if the hook's authority context does not match the mod's design.

How the Mod Hooks system works

Mod Hooks are standard Unity MonoBehaviour scripts that appear in the Unturned components menu in the Unity Editor after the Project.unitypackage is imported. The mod developer attaches one or more hook scripts to a GameObject in the prefab hierarchy, configures the hook's parameters in the Inspector, and wires the hook's UnityEvents to target methods on other components -- activating a GameObject, playing an Animation, spawning a prefab, changing a material, and so on. When the prefab is exported in an asset bundle and loaded by the game at runtime, the hooks fire their events according to the conditions each hook defines.

The system is intentionally limited to the scripts that ship in the base game code. A mod developer cannot write a custom hook script and export it in a bundle; only the scripts whose names and types match scripts that exist in the base game's C# assembly will be loaded by the game. This restriction exists because Unity's asset bundle security model prevents arbitrary code execution from unverified bundles. The hooks that are available are the set that the game developers have explicitly chosen to export and maintain, and the set grows when game updates add new hook types.

Each hook script exposes one or more UnityEvent fields in the Inspector. A UnityEvent is a serialized event reference that can be wired to call methods on other components in the same prefab or scene. The mod developer drags a target GameObject into the event slot, selects a component from the dropdown, and chooses a method from the component's public API. When the hook fires the event at runtime, Unity invokes all of the wired methods in the order they appear in the Inspector, passing any configured parameters to each method.

As shown in the flowchart above, the hook sits between the game's simulation events and the mod developer's desired behavior, translating a gameplay condition into a UnityEvent that the mod developer can wire to any component action the prefab supports. The hook is a relay: it detects a condition in the game world and converts that condition into a Unity event invocation, and the mod developer's wiring determines what happens in response.

The authority context: server versus client

Every Mod Hook operates in a specific authority context, and understanding this context is essential for multiplayer mod development. A hook that fires "on the server" means the hook's events only execute on the server instance of the prefab and are not fired on connected clients. A hook that fires "on the server and client" means the hook's events execute on every instance of the prefab, both server and client. A hook that fires "primarily on the server" means the hook has a documented limitation that reduces its utility on the client side, even though the hook may technically fire on both server and client instances.

The authority context matters because a client-side-only effect (an animation, a particle system, a material change) wired to a server-only hook will fire on the server but not on any connected client. The server will see the effect, but no player will. Conversely, a server-side action (spawning an item that all players should receive) wired to a client-side hook will fire for one player but not affect the shared game state. The authority context for each hook is documented in its individual entry in the sections below.

Hook categories

The Mod Hooks system divides into three categories based on the direction of event flow relative to the game world:

Category	Count	Direction	Description
Event Listeners	21	World → Prefab	These hooks listen for game events (collisions, state changes, timers, weather transitions) and fire UnityEvents on the prefab in response to those events.
Event Instigators	9	Prefab → World	These hooks let the prefab instigate game events: spawning items, placing barricades, broadcasting chat messages, triggering airdrops, and so on.
Misc	6	Varies	Utility hooks that modify crafting tags, override fall damage, destroy barricades, repeat events, or route audio through the music mixer.

Event Listeners

Event listeners are hooks that fire UnityEvents in response to game-world conditions. They are the most frequently used hook category and the entry point for most hook-driven mod behavior. Each listener detects a specific condition (a GameObject being enabled, a player entering a trigger, a timer expiring, the weather changing) and fires the corresponding UnityEvent when that condition is met.

Activation Event Hook

The Activation Event Hook fires events when a component or GameObject is enabled or disabled. This is the hook used for extending toggleable actions in the base game. When the GameObject this hook is attached to becomes active (the Unity OnEnable lifecycle message is received), the OnEnabled UnityEvent fires. When the GameObject becomes inactive (the Unity OnDisable lifecycle message is received), the OnDisabled UnityEvent fires.

Parameters: None beyond the two UnityEvent fields (OnEnabled, OnDisabled).

Authority context: Fires on both the server and the client.

Primary use case: Enabling or disabling a secondary effect when a toggleable object changes state. A light that turns on when a generator GameObject is enabled; a sound effect that plays when a trap is disabled; a particle system that activates when a machine is powered on.

Wiring example: Attach an Activation Event Hook to a generator GameObject. Wire OnEnabled to a child Light component's Activate method. Wire OnDisabled to the same Light component's Deactivate method. When the generator becomes active, the light turns on. When the generator becomes inactive, the light turns off.

Binary Random Component

The Binary Random Component fires one of two events depending on a percentage probability. The component exposes a probability value (a float between 0.0 and 1.0) and two UnityEvent fields (OnTrue and OnFalse). When the component's Trigger method is called (which must be wired from another hook's event, because the Binary Random Component does not listen for any game condition on its own), it evaluates a random roll against the configured probability and fires either OnTrue or OnFalse.

Parameters: Probability (float, 0.0 to 1.0, default 0.5).

Authority context: Fires on both the server and the client.

Primary use case: Adding randomness to mod behavior. A loot crate that has a small chance of spawning a rare item; a trap that sometimes fails to activate; an NPC interaction that produces different dialogue outcomes; a spawner that occasionally produces a special variant.

Wiring example: Wire a Destroy Event Hook's event to a Binary Random Component's Trigger method. Set the probability to 0.05. Wire OnTrue to an Item Spawner configured to spawn a rare item. Wire OnFalse to an Item Spawner configured to spawn a common item. When the GameObject is destroyed, five percent of the time the rare item spawns; ninety-five percent of the time the common item spawns.

Collision Damage

The Collision Damage hook damages players when they overlap a trigger collider on the same GameObject. It is a specialized hook for creating environmental damage volumes: lava pits, radiation zones, acid pools, and any other area that damages players who enter it. The hook requires a Collider component with Is Trigger enabled on the same GameObject.

Parameters: Damage amount (float), damage type (enum), tick interval (float, in seconds).

Authority context: Fires on the server only. The damage application is server-authoritative.

Primary use case: Environmental hazard volumes. A lava pit in a custom map that damages players standing in it; a radiation zone that applies damage-over-time; an electric fence that damages players who touch it.

Collision Event Hook

The Collision Event Hook fires events for player overlaps with a trigger collider. The hook exposes OnPlayerEnter and OnPlayerExit UnityEvents. The hook only reports collisions with colliders on the Player layer (layer 9), which has a significant consequence for multiplayer: on the client, only the locally-controlled character is on the Player layer. Other connected players' characters are on the Enemy layer (layer 10). This means the Collision Event Hook detects only the local player on the client but detects all players on the server. The official SDG documentation states that this hook is "primarily useful for server-side objects."

Parameters: None beyond the two UnityEvent fields (OnPlayerEnter, OnPlayerExit). The trigger collider must be configured on the same GameObject.

Authority context: Fires on both the server and the client, but only detects the local player on the client. Primarily useful for server-side objects.

Primary use case: Player-detection trigger volumes. An automatic door that opens when any player approaches; a checkpoint trigger that records a player's progress; a boss-arena entry detector that starts an encounter.

Wiring example: Attach a Collision Event Hook and a Box Collider (with Is Trigger enabled) to an empty GameObject positioned at a doorway. Wire OnPlayerEnter to the door model's GameObject.SetActive method (set to true for an opening animation). Wire OnPlayerExit to a Timer Event Hook's StartTimer method, and wire the timer's OnTimerExpired to the door's GameObject.SetActive method (set to false). The door opens when a player approaches and closes after a delay when the player leaves.

Destroy Event Hook

The Destroy Event Hook fires an event when a component or GameObject is removed from the scene. The hook responds to the Unity OnDestroy lifecycle message on the attached GameObject or component. The OnDestroyed UnityEvent fires once at the moment of destruction, and any wired methods execute before the GameObject is fully removed from the scene hierarchy.

Parameters: None beyond the single UnityEvent field (OnDestroyed).

Authority context: Fires on both the server and the client.

Primary use case: Destruction responses. A crate that spawns item pick-ups when destroyed; a barricade that broadcasts a chat message when salvaged; an enemy that spawns a death effect when killed; a destructible prop that plays a collapse animation before removal.

Explosion Spawner

The Explosion Spawner allows Unity events to apply damage in a sphere. It does not produce any visual effects on its own; it is purely a damage-application mechanism. The hook is intended to replace unsupported or unintentional use of Grenade.cs and Rocket.cs scripts in mod content, which are internal game scripts that mod developers were previously using for area damage because no official hook provided the functionality.

Parameters: Explosion radius (float, in meters), damage amount (float), damage type (enum).

Authority context: Fires on the server only. The damage application is server-authoritative.

Primary use case: Area-of-effect damage triggers. A landmine that damages everything in a radius when stepped on; a barrel that explodes when shot; a boss attack that deals area damage. Pair this hook with an Effect Spawner wired to the same trigger event to produce a visible explosion effect alongside the damage.

Gun Attachment Event Hook

The Gun Attachment Event Hook allows gun item GameObjects, including their children, to receive events when sights, tacticals, grips, barrels, and magazines are attached, replaced, or detached. The hook is attached to the gun prefab or to a child GameObject within the gun prefab hierarchy.

Parameters: Ten UnityEvent fields, one pair (OnAttached and OnDetached) for each of the five attachment types: Sight, Tactical, Grip, Barrel, Magazine. Each event carries a reference to the specific attachment item that was attached or detached.

Authority context: Fires on both the server and the client.

Primary use case: Attachment-reactive weapon behavior. A laser sight GameObject that activates when a tactical attachment is equipped; a weapon model that changes its magazine appearance when a specific magazine type is loaded; a scope overlay that enables when a sight attachment is attached.

Interactable Object Binary State Event Hook (IOBS)

The Interactable Object Binary State Event Hook (IOBS for short) is attached to any GameObject within an IOBS prop. An IOBS is any prop placed from the level editor which can have the F key pressed on it to open, close, turn on, or turn off. The hook fires events during state changes and can even control the IOBS from client and server side through its public methods.

Parameters: UnityEvent fields for the two binary states (OnOpened, OnClosed, or the equivalent state names for the specific IOBS type). Public methods to programmatically toggle the state.

Authority context: Fires on both the server and the client.

Primary use case: Interactive level objects with custom responses. A door that plays a sound and spawns particles when opened; a light switch that toggles multiple lights simultaneously; a generator that broadcasts a chat message when activated; a valve that triggers an airdrop when turned.

Interactable Object Quest Event Hook

The Interactable Object Quest Event Hook can be added to any GameObject within a Dropper, Note, or Quest Interactable Object. Its UnityEvent is triggered when the corresponding interactable is successfully used by a player. The event is only triggered on the authority side (the server or the singleplayer host), not on the client.

Parameters: None beyond the single UnityEvent field. The hook detects the parent interactable's use event.

Authority context: Fires on the server (authority) only. Does not fire on connected clients.

Primary use case: Quest-progression triggers tied to world objects. A note that advances a quest when read; a dropper that fires a quest-completion event when a player deposits the required item; a quest interactable object that broadcasts a global NPC event when activated.

NPC Global Event Hook

The NPC Global Event Hook triggers when a corresponding NPC Event reward type is broadcast. An NPC Event is a named event identified by a string ID that NPC dialogue or quest rewards can broadcast through the game's NPC system. When any NPC Event with a given ID is broadcast anywhere in the game world, all NPC Global Event Hook components configured with that event ID have their Unity event triggered.

Parameters: Event ID (string) -- the hook listens for NPC Events with this ID.

Authority context: Fires on both the server and the client.

Primary use case: Decoupled pub-sub event system for cross-prefab communication. When an NPC Event with ID "Fireworks" is broadcast (from an NPC dialogue reward or from an NPC Global Event Messenger instigator hook), all NPC Global Event Hook components with event ID "Fireworks" fire their events, perhaps to spawn a fireworks effect at different locations across the map. This hook creates the ability for NPC interactions to trigger world effects without the NPC and the effects needing to be in the same scene, prefab, or even the same asset bundle.

Text Chat Event Hook

The Text Chat Event Hook fires an event when a text chat message passes certain filters. The hook is configured with a channel filter (Global, Local, Group), a radius filter (the message must originate within this distance of the hook's GameObject), and a secret phrase filter (the message text must contain this string). Only messages that pass all active filters trigger the event. The hook only fires on the server.

Parameters: Channel (enum: Global, Local, Group), radius (float, in meters), secret phrase (string).

Authority context: Fires on the server only. Chat messages are server-authoritative.

Primary use case: Chat-activated world interactions. A secret password spoken in local chat that opens a hidden door; a ritual phrase that spawns a boss enemy; a command word that activates a server event; a puzzle solution that the player must type into chat.

Timer Event Hook

The Timer Event Hook allows events to set or cancel a timer, and triggers a UnityEvent when the timer expires. The hook exposes a StartTimer method (takes a duration in seconds), a CancelTimer method, and an OnTimerExpired UnityEvent.

Parameters: None in the Inspector beyond the UnityEvent field. The timer duration is passed as an argument to the StartTimer method at wiring time.

Authority context: Fires on both the server and the client.

Primary use case: Delayed and timed event sequences. A pressure plate that resets after a 3-second delay; a door that automatically closes 5 seconds after being opened; a trap that arms itself after a 10-second countdown; a sequence of events that must fire with specific time gaps between them (chain multiple Timer Event Hook components, each starting the next).

Useable Event Hook

The Useable Event Hook fires events for the EquipableItem prefab of any item type. The events fire on both the server and the client. The hook exposes events for item equip, dequip, and use actions, making it the generic mechanism for attaching custom behavior to item usage regardless of item type.

Parameters: UnityEvent fields for OnEquipped, OnDequipped, OnUsed.

Authority context: Fires on both the server and the client.

Primary use case: Item-use responses for any item type. A medkit that spawns a healing particle effect when used; a flare gun that broadcasts a chat message when fired; a tool that plays a custom animation when equipped.

Useable Gun Event Hook

The Useable Gun Event Hook fires events for the EquipableItem prefab of gun items specifically. This hook supersedes the Vehicle Turret Event Hook for gun-specific behavior. The events fire on both the server and the client, and the hook exposes gun-specific events including fire, reload, and aim actions.

Parameters: UnityEvent fields for gun-specific actions: OnFired, OnReloaded, OnAimStarted, OnAimStopped.

Authority context: Fires on both the server and the client.

Primary use case: Gun-specific behavior that the generic Useable Event Hook cannot detect. A weapon that plays a custom muzzle-flash effect on fire; a shotgun that spawns shell casings during reload; a sniper rifle that changes its scope overlay when aiming.

Vehicle Event Hook

The Vehicle Event Hook fires events for the driver entering and exiting the vehicle. These events fire on both the server and the client. The hook exposes OnDriverEntered and OnDriverExited UnityEvents, each carrying a reference to the player who entered or exited.

Parameters: None beyond the two UnityEvent fields.

Authority context: Fires on both the server and the client.

Primary use case: Vehicle-reactive world behavior. A garage door that opens when a vehicle approaches; a vehicle that broadcasts a chat message when entered; a car alarm that plays a sound when an unauthorized player enters.

Vehicle Gear Shift Event Hook

The Vehicle Gear Shift Event Hook fires events for the vehicle gearbox entering and exiting a target gear. The hook is configured with a target gear index and exposes OnGearEntered and OnGearExited UnityEvents for that specific gear.

Parameters: Target gear index (integer), UnityEvent fields for OnGearEntered and OnGearExited.

Authority context: Fires on both the server and the client.

Primary use case: Gear-reactive vehicle behavior. An engine sound that changes pitch when the vehicle shifts to a higher gear; a turbo-boost visual effect that activates in the highest gear; a speed-based trigger that fires when the vehicle reaches the gear associated with a target speed threshold.

Vehicle Health Event Hook

The Vehicle Health Event Hook fires events for vehicle health passing a comparison against a target number. The hook is configured with a target health value and a comparison operator (greater than, less than, or equal to) and exposes UnityEvents for each comparison direction.

Parameters: Target health value (float), comparison operator (enum: GreaterThan, LessThan, EqualTo), UnityEvent fields for OnHealthAbove and OnHealthBelow.

Authority context: Fires on both the server and the client.

Primary use case: Damage-reactive vehicle behavior. A smoke effect that activates when vehicle health drops below fifty percent; an explosion that triggers when health reaches zero; a repair indicator that activates when health is above ninety percent; a boss vehicle that changes its attack pattern when health drops below a threshold.

Vehicle Turret Event Hook

The Vehicle Turret Event Hook fires events for Turret_# GameObjects in the vehicle when guns mounted on those turrets are used. These events fire on both the server and the client. The hook responds to turret-mounted weapons specifically, not to handheld weapons used from within the vehicle.

Parameters: UnityEvent fields for turret fire events.

Authority context: Fires on both the server and the client.

Primary use case: Turret-mounted weapon behavior. A muzzle flash effect when a vehicle turret fires; an ammo-counter display that updates when the turret is used. Note that the Useable Gun Event Hook supersedes this hook for most gun-related behavior; the Vehicle Turret Event Hook is retained for compatibility with older mods and for turret-specific scenarios.

Weather Event Hook

The Weather Event Hook fires events for day, night, full moon, and weather transitions. These events fire on both the server and the client. The hook exposes UnityEvents for OnDay, OnNight, OnFullMoon, and individual weather type transitions (rain begins, rain ends, storm begins, storm ends, and so on).

Parameters: UnityEvent fields for each weather transition type the hook supports.

Authority context: Fires on both the server and the client.

Primary use case: Environment-reactive world behavior. Street lights that turn on at night; enemy spawners that activate during a full moon; ambient sound emitters that play during rain; NPC dialogue that changes based on the current weather.

Custom Weather Event Hook

The Custom Weather Event Hook fires events for a specific custom Weather Asset. Any map can define an unlimited number of custom weather types and weather listeners. The hook is configured with a reference to a specific custom weather asset and fires events when that weather type begins and ends.

Parameters: Custom weather asset reference (asset field), UnityEvent fields for OnWeatherBegan and OnWeatherEnded.

Authority context: Fires on both the server and the client.

Primary use case: Custom-weather reactivity. A custom "eclipse" weather type that triggers special enemy spawns; a "heat wave" weather that applies damage-over-time to players; a "bloom" weather that spawns harvestable resources across the map; a "sandstorm" weather that reduces visibility and plays a wind sound.

Event Instigators

Event instigators are hooks that allow the prefab to instigate game-world events. They are typically wired as the target of a listener hook's event: a Collision Event Hook detects a player entering a trigger and fires its OnPlayerEnter event, which is wired to an Item Spawner instigator's Spawn method, causing a loot item to appear in the world. The instigator hooks are the "action" half of the hook system; they convert UnityEvent invocations into tangible changes in the game world.

Airdrop Spawner

The Airdrop Spawner allows Unity events to call in an airdrop. The hook is configured with optional overrides for the cargo (the items delivered) and the destination (the drop coordinates). When the hook's CallAirdrop method is invoked through a wired UnityEvent, the game spawns an airdrop plane that flies across the sky and drops the cargo at the configured destination or at a default location.

Parameters: Cargo override (item table reference, optional), destination override (Vector3, optional).

Authority context: Server-authoritative. The airdrop is a server-managed event.

Primary use case: Event-driven supply delivery. A puzzle completion that rewards the player with an airdrop; a boss defeat that calls in supply crates; a server event timer that drops care packages at regular intervals; a quest turn-in that delivers faction supplies.

Barricade Spawner

The Barricade Spawner allows Unity events to place barricades in the world. The hook is configured with a reference to the barricade item to spawn (by item ID) and the placement position relative to the hook's GameObject. When the hook's Spawn method is invoked, the barricade is instantiated at the configured position.

Parameters: Barricade item ID (uint16), spawn position (Vector3, relative or world-space).

Authority context: Server-authoritative. Barricade placement is a server-managed action.

Primary use case: Deployable barricades triggered by events. A button that deploys a temporary barrier wall; a trap that spawns spike barricades around the player who triggered it; a puzzle that reveals a hidden storage crate when solved; a defensive emplacement that spawns sandbags when activated.

Client Text Chat Messenger

The Client Text Chat Messenger allows Unity events to request a text chat message be sent on behalf of the client. The hook is configured with the message text and an optional flag to treat the message as a command to execute rather than a chat message to display.

Parameters: Message text (string), execute as command (bool).

Authority context: Client-side, but requires server configuration to be enabled. The UnityEvents.Allow_Client_Messages and UnityEvents.Allow_Client_Commands settings must be enabled in the server configuration before this hook can function. Singleplayer defaults to enabled.

Primary use case: Client-side commands and messages. A trigger that runs a teleport command for the player who entered it; a terminal that executes a give-item command; an interactive object that sends a message to the player's chat. This hook is one of the most powerful in the system because command execution allows extending hook-driven behavior to any server command, but it is also one of the most security-sensitive because it allows client-side mod content to execute server commands.

Item Spawner

The Item Spawner allows Unity events to spawn dropped items in the world. The hook is configured with a reference to the item to spawn (by item ID) and the spawn position relative to the hook's GameObject. When the hook's Spawn method is invoked, the item is instantiated as a dropped world item on the Item layer (layer 13) that players can pick up through the standard interaction system.

Parameters: Item ID (uint16), spawn position (Vector3, relative or world-space), quantity (integer, optional).

Authority context: Server-authoritative. Item spawning is a server-managed action.

Primary use case: Loot generation and item delivery. A chest that spawns randomized loot when opened; a defeated enemy that drops items; a puzzle reward that spawns a specific item at the puzzle's location; a resource node that drops harvested materials when depleted.

Server Text Chat Messenger

The Server Text Chat Messenger allows Unity events to broadcast messages from the server. The hook is configured with the message text, optional rich text formatting, optional icon display, and an optional flag to execute the message as a server command. Commands that are not yet available to NPCs (such as changing the weather or triggering an airdrop) can be executed through this hook.

Parameters: Message text (string), rich text enabled (bool), icon ID (string, optional), execute as command (bool).

Authority context: Server-authoritative. Requires UnityEvents.Allow_Server_Messages and UnityEvents.Allow_Server_Commands to be enabled in the server configuration. Singleplayer defaults to enabled.

Primary use case: Server-wide announcements and command sequences. A global event that broadcasts a message to all players; a timed server event that changes the weather and announces the change in chat; a boss encounter that announces phase transitions; a puzzle that announces the first player to solve it.

Effect Spawner

The Effect Spawner allows Unity events to spawn effect assets. The hook is configured with a reference to the effect asset (a Unity prefab with a particle system or visual effect) and the spawn position. When the AuthorityOnly field is enabled, only the server spawns the effect and replicates it to clients; when disabled, each client spawns the effect locally, which is faster but may produce inconsistent results if the effect needs to be seen by all players.

Parameters: Effect asset reference (asset field), spawn position (Vector3), AuthorityOnly (bool).

Authority context: Depends on the AuthorityOnly setting. When true, server-authoritative with client replication. When false, each client spawns locally.

Primary use case: Visual feedback from hook-driven events. A particle burst when an item is picked up; a muzzle flash when a turret fires; a smoke plume when a generator activates; a beam of light when a quest objective is completed.

Mob Alert Spawner

The Mob Alert Spawner allows Unity events to startle nearby animals and zombies. The hook is configured with an alert radius and optionally uses a nearby player as the origin of the alert. When the hook's Alert method is invoked, AI entities within the configured radius receive an alert stimulus that causes them to investigate the alert origin or become aggressive.

Parameters: Alert radius (float, in meters), use player as origin (bool).

Authority context: Server-authoritative. AI behavior is managed by the server.

Primary use case: Hazard and encounter triggers. A noise trap that attracts zombies when a player enters a building; a flare that startles animals in the vicinity; a boss encounter that summons additional mobs when the boss reaches a health threshold; a gunshot sound trap that draws zombies to the player's location.

NPC Global Event Messenger

The NPC Global Event Messenger allows Unity events to broadcast NPC Event rewards. The hook is configured with an event ID (a string identifier), and when the hook's Broadcast method is invoked, any NPC Global Event Hook components configured with the same event ID fire their UnityEvents in response.

Parameters: Event ID (string).

Authority context: Server-authoritative.

Primary use case: Global event distribution across independent prefabs. A puzzle that broadcasts a completion event which triggers effects across the entire map; a boss defeat that broadcasts a victory event which opens sealed doors in multiple locations; a timed sequence that broadcasts phase-change events which drive multi-stage encounters with different prefabs responding to each phase.

Vehicle Spawner

The Vehicle Spawner allows Unity events to spawn a vehicle. The hook is configured with a reference to the vehicle asset to spawn and the spawn position. It optionally overrides the paint color of the spawned vehicle.

Parameters: Vehicle asset reference (asset field), spawn position (Vector3), paint color override (Color, optional).

Authority context: Server-authoritative. Vehicle spawning is a server-managed action.

Primary use case: Vehicle delivery and encounter vehicles. A garage button that spawns the player's stored vehicle; a race event that spawns vehicles at the starting line; a mission reward that delivers a vehicle; a boss arena that spawns an escape vehicle after the boss is defeated.

Misc hooks

The Misc category contains utility hooks that do not fit cleanly into the listener or instigator categories. These hooks provide specialized functionality and are used in specific mod scenarios.

Barricade Destroyer

The Barricade Destroyer forcefully removes barricades within a sphere. The hook is configured with a radius and boolean flags for optional behaviors: playing the barricades' explosion effects and spawning their Item_Dropped_On_Destroy item drops, which are the standard barricade destruction rewards.

Parameters: Radius (float, in meters), play explosion effects (bool), spawn destroy drops (bool).

Authority context: Server-authoritative. Barricade destruction is a server-managed action.

Primary use case: Area-clear effects. A demolition charge that clears barricades in a radius; a cleanup trigger that removes temporary obstacles after an encounter; a boss ability that destroys player-placed defenses in an arena; a map reset trigger that clears all barricades in a zone.

Fall Damage Override

The Fall Damage Override allows any GameObject to override the fall damage calculation when a character lands on it or one of its descendants. The hook is configured with a fall damage multiplier, where 0.0 means no fall damage, 1.0 means normal fall damage, and values between 0.0 and 1.0 reduce fall damage proportionally.

Parameters: Fall damage multiplier (float, 0.0 to 1.0, default 0.0).

Authority context: The override is active on both server and client, but fall damage is calculated server-authoritatively.

Primary use case: Soft-landing surfaces. A hay bale that negates fall damage; a trampoline that reduces fall damage by half; a water surface that applies zero fall damage; a cushioned surface in a parkour map that prevents fall-death during traversal.

Crafting Tag Provider

The Crafting Tag Provider allows barricades, structures, vehicles, resources, and objects to modify which crafting tags (workstation categories) are available to nearby players. The hook is attached to the entity that provides the crafting radius, and one or more linked Crafting Tag Modifier components define which specific tags are added to or removed from the available pool.

Parameters: None on the provider itself beyond the link to modifiers. The provider defines the radius and entity association.

Authority context: Server-authoritative. Crafting availability is managed by the server.

Primary use case: Custom workstation radii. A campfire that provides the "Heat Source" crafting tag to nearby players (the vanilla use case); a custom workbench that provides multiple crafting tags; a vehicle that functions as a mobile workstation; a structure that enables specific crafting recipes when powered.

Crafting Tag Modifier

The Crafting Tag Modifier is linked from a Crafting Tag Provider and allows Unity events to modify which crafting tags are available to nearby players. The modifier is configured with a target crafting tag name, an activation requirement, and a mode.

Parameters: Target tag (string, the crafting tag name to modify), activation requirement (enum: Always, Invert, or linked to a UnityEvent), mode (enum: Add or Remove).

Authority context: Server-authoritative. Controlled by the activation requirement; can be driven by UnityEvents.

Primary use case: Conditional crafting availability. The vanilla Heat Source backwards compatibility uses this hook: a Crafting Tag Modifier is added to the Fire GameObject with an activation requirement of Invert and mode Remove. This removes the Heat Source tag while the Fire is inactive, so players can only cook when the fire is lit. When the fire is extinguished, the Heat Source tag is removed, and cooking recipes requiring a heat source become unavailable until the fire is relit.

Music Audio Source

The Music Audio Source reassigns a sibling AudioSource component's output audio mixer group to the vanilla Music mixer, which respects the player's configured music volume setting. The hook is attached to the same GameObject as an AudioSource component and routes that audio source through the music mixer channel rather than through the general sound effects channel.

Parameters: None beyond the requirement that a sibling AudioSource component is present.

Authority context: Client-side. Audio routing is per-client.

Primary use case: Custom music playback at the player's configured music volume. A jukebox barricade that plays music; a radio in a vehicle that plays songs; ambient music that plays when a player enters a specific area; a boss encounter that triggers a battle music track.

Repeat

The Repeat hook repeats an event a configurable or random number of times. It is a for-loop for Unity events: when the hook's Trigger method is invoked, it fires the configured UnityEvent the specified number of times in sequence.

Parameters: Repeat count (integer, or a random range defined by min and max integers), UnityEvent to repeat.

Authority context: Fires on both the server and the client. The authority context of the wired event depends on the target component.

Primary use case: Repeated effect sequences. Spawning a burst of ten items from a loot crate; firing a series of five explosions along a path; playing a sequence of three sounds with equal time gaps between them; spawning a wave of enemies in rapid succession.

Hook registration and lifecycle

Mod Hooks do not require explicit registration. They are Unity components attached to GameObjects in the Unity Editor and exported as part of the prefab in the asset bundle. At runtime, when the game loads the asset bundle, it instantiates the prefab and all of its attached components, including any Mod Hook scripts. The hooks begin responding to their trigger conditions immediately upon instantiation, following the standard Unity component lifecycle.

The lifecycle of a Mod Hook is tied to the lifecycle of its host GameObject. When the GameObject is instantiated (spawned in the world, loaded from a bundle), the hook's Awake, OnEnable, and Start methods execute in the standard Unity order. The hook begins listening for its trigger conditions, subscribing to game events if it is a listener-type hook. When the GameObject is destroyed (removed from the scene, destroyed by gameplay), the hook's OnDisable and OnDestroy methods execute, the hook unsubscribes from its trigger conditions, and any pending timers or state are cleaned up.

For server-only hooks (hooks that only fire on the server, such as Text Chat Event Hook and Collision Damage), the hook is active only on the server instance of the prefab. The client instance of the same prefab has the hook component present in memory, but the hook's internal code checks network authority conditions (NetworkServer.active or equivalent) before firing events, and the events do not execute on the client side. This is enforced by each hook's own code, not by any external system.

Hook parameters and return values

Mod Hooks expose their configuration through public fields in the Unity Inspector. The specific fields vary by hook type and are documented in each hook's *.cs source file in the base game code, which is readable after importing the Project.unitypackage. Common parameter types that recur across hook types include:

Parameter type	Example fields	Description
Float	Probability, radius, duration, damage amount	A decimal number; configured through a number field in the Inspector. Supports decimal precision.
Integer	Count, gear index, item ID	A whole number; configured through an integer field. Item IDs are uint16 values.
Boolean	AuthorityOnly, execute as command, play effects	A true/false flag; configured through a checkbox in the Inspector.
String	Event ID, secret phrase, message text, tag name	A text string; configured through a text field. Event IDs are case-sensitive.
Asset reference	Weather asset, effect asset, vehicle asset	A reference to a game asset; configured through an object field or a text field containing the asset's GUID or path.
UnityEvent	OnEnabled, OnTrue, OnPlayerEnter, OnTimerExpired	An event slot; configured by dragging target GameObjects into the slot and selecting target component methods from the dropdown.

Mod Hooks do not have return values in the traditional programming sense. The hook fires a UnityEvent, and any wired methods execute in sequence, but the hook itself does not receive a return value from those methods and does not branch based on the result. The event wiring determines what happens when the hook fires; the hook's sole responsibility is to detect the trigger condition and invoke the event.

Common hook patterns and validated use cases

The following table documents recurring hook combination patterns that the cohort has validated across Unturned™ mod projects. Each pattern describes a chain of hooks and the gameplay behavior it produces.

Pattern	Hook chain	Description
Automatic door	Collision Event Hook (OnPlayerEnter) → Timer Event Hook (StartTimer) → door GameObject.SetActive (true). Separate: Collision Event Hook (OnPlayerExit) → Timer Event Hook (StartTimer, longer delay) → door GameObject.SetActive (false)	Player enters trigger zone → door opens immediately. Player exits trigger zone → timer starts → door closes after a configurable delay.
Randomized loot crate	Destroy Event Hook (OnDestroyed) → Binary Random Component (Trigger, probability 0.05) → OnTrue → Item Spawner (rare item). OnFalse → Item Spawner (common item)	Crate destroyed → five percent chance of rare loot, ninety-five percent chance of common loot.
Chat-activated boss encounter	Text Chat Event Hook (secret phrase "challenge") → Server Text Chat Messenger (broadcast "The boss awakens!") → Vehicle Spawner (boss vehicle asset)	Player types the secret phrase in chat → server broadcasts acknowledgment → boss vehicle spawns at the hook's location.
Day-night reactive lighting	Weather Event Hook (OnNight) → Light.SetActive (true). Weather Event Hook (OnDay) → Light.SetActive (false)	Night begins → street lights activate. Day begins → lights deactivate.
Airdrop puzzle reward	Interactable Object Binary State Event Hook (OnOpened) → Airdrop Spawner (CallAirdrop)	Player solves a puzzle (toggles an IOBS to its opened state) → airdrop is called to the player's location.
Multi-stage boss encounter	Vehicle Health Event Hook (OnHealthBelow, threshold 50%) → NPC Global Event Messenger (Broadcast, event ID "boss_phase_2") → remote NPC Global Event Hook (ID "boss_phase_2") → Effect Spawner + Mob Alert Spawner	Boss health drops below fifty percent → phase-change event broadcast → effects spawn and additional mobs are alerted across the arena.
Timed trap sequence	Collision Event Hook (OnPlayerEnter) → Timer Event Hook (StartTimer, 2-second arm delay) → trap activation GameObject.SetActive (true) → second Timer Event Hook (StartTimer, 5-second active duration) → trap GameObject.SetActive (false)	Player enters trigger → 2-second arm delay → trap activates for 5 seconds → trap deactivates and resets.
Vehicle garage	Collision Event Hook (vehicle trigger zone, OnPlayerEnter) → garage door open animation. Vehicle Event Hook (OnDriverExited) → Timer Event Hook (StartTimer, delay) → garage door close animation	Vehicle enters garage trigger → door opens. Driver exits vehicle → timer starts → door closes after delay.
Crafting station activation	Activation Event Hook (OnEnabled, linked to a power switch IOBS) → Crafting Tag Modifier (mode Add, tag "Workbench")	Power switch turned on → crafting tag added → nearby players can craft workbench recipes. Switch turned off → tag removed.
Weather-reactive spawner	Custom Weather Event Hook (OnWeatherBegan, eclipse weather) → Mob Alert Spawner + Server Text Chat Messenger (broadcast "The eclipse darkens the land...")	Custom eclipse weather begins → mobs are alerted across the map → server broadcasts an atmospheric message.

How to wire hook events in the Unity Inspector

The following step-by-step workflow describes the standard process for wiring a Mod Hook's UnityEvents to target component methods. This workflow is performed in the Unity Editor before the asset bundle is exported.

1. Select the GameObject that has the Mod Hook script attached in the Hierarchy window.
2. In the Inspector, scroll to the hook's event field (the label will read OnEnabled, OnPlayerEnter, OnTimerExpired, or whatever the hook names its UnityEvent). The event field is a foldout section with a + and - button at the bottom.
3. Click the + button at the bottom of the event field to add a new event slot. An empty slot appears with an object field and a function dropdown.
4. Drag the target GameObject from the Hierarchy into the object field of the new event slot. The target GameObject is the object whose component method should be invoked when the event fires. This can be the same GameObject, a child GameObject, or any other GameObject in the same prefab hierarchy.
5. Click the function dropdown (initially reads "No Function"). Navigate through the component hierarchy to select the target component, then select the specific method to invoke. Only public methods that match the event's parameter signature appear in the dropdown.
6. If the selected method accepts a parameter (a float value, a string, a GameObject reference, a bool), a parameter field appears below the method dropdown. Enter the value to pass to the method when the event fires.
7. Repeat steps 3 through 6 for each additional wired method. Methods fire in the order they appear in the Inspector, top to bottom.

The UnityEvent wiring is serialized in the prefab data and persists through the asset bundle export process. The wired methods execute at runtime exactly as they execute in the Unity Editor during Play mode testing, with the same parameter values and invocation order.

Testing hook configurations in the Unity Editor

Mod Hooks respond to standard Unity lifecycle events in the Unity Editor's Play mode as well as in the built game. This allows rapid iteration on hook configurations without the cycle time of building and deploying an asset bundle. The following testing workflow is the cohort-validated approach:

1. Create a test scene in the Unity project that contains the prefab under development.
2. Attach the Mod Hook scripts and wire the events as desired.
3. Enter Play mode.
4. Trigger the hook's conditions manually: enable or disable the GameObject for Activation Event Hook, walk a test character into a trigger volume for Collision Event Hook, call the hook's public methods through the Inspector's context menu (right-click the component header and select the method to invoke).
5. Observe the wired effects. Confirm that the correct component methods execute, that animations play, that GameObjects activate and deactivate, and that spawners produce the expected results.
6. Exit Play mode, adjust the wiring or parameters as needed, and re-enter Play mode to verify.

The cohort recommendation is to test every wired event in Play mode at least once before exporting the asset bundle. A wiring error that would take several seconds to catch in the Editor can take several minutes to catch through the build-deploy-test cycle, and the cumulative time savings across a large mod project are substantial.

Diagnostic table: common hook wiring problems

Symptom	Most likely cause	Resolution
Hook event appears to fire but nothing happens	Target method not wired, or wired to wrong GameObject	Check the event slot in the Inspector; confirm the object field is populated and the function dropdown is set to a valid method
Hook event fires in singleplayer but not on dedicated server	Hook is server-authoritative but the wired effect is client-side only, or the hook only fires for the local player on the client	Check the hook's authority context in this reference; move the effect to the server or use a hook that fires on both server and client
Collision Event Hook only detects local player in multiplayer	By design: the hook only detects Player layer collisions, and other players are on Enemy layer client-side	Use server-side hooks and broadcast results through NPC Global Event Messenger, or accept the singleplayer limitation
Timer starts but never fires	Timer duration set to 0 or very long; or the timer's StartTimer method was wired without a duration argument	Check the duration argument passed to StartTimer in the event wiring; confirm it is a positive number
Binary Random Component always fires OnFalse	Probability set to 0.0 or very low	Increase the probability value to the desired ratio
Text Chat Event Hook never fires	Secret phrase does not match; channel filter does not match; or the player is not within the radius filter	Verify the secret phrase spelling and case; check the channel filter; confirm the player is within the configured radius
Crafting tag does not appear for nearby players	Crafting Tag Modifier activation requirement is not met, or the linked Crafting Tag Provider is on the wrong entity	Check the activation requirement setting; confirm the provider is attached to a valid entity type (barricade, structure, vehicle, resource, or object)
Effect Spawner effect only visible to host	AuthorityOnly is enabled and the effect is not replicated, or the effect spawned on a client-side-only path	Set AuthorityOnly to true and ensure the spawning event fires on the server side
Client Text Chat Messenger does not execute commands	Server configuration has UnityEvents.Allow_Client_Commands disabled	Enable the setting in the server configuration, or use Server Text Chat Messenger instead
Multiple hooks on the same GameObject interfere with each other	Wiring order or timing conflict between hook events	Check the event wiring order in the Inspector; consider adding a Timer Event Hook with a small delay to sequence the events

Best practices

• Test every Mod Hook configuration in the Unity Editor's Play mode before exporting the asset bundle. Editor testing catches wiring errors that would otherwise require a full build cycle to diagnose.
• Use the NPC Global Event Hook and NPC Global Event Messenger system for decoupled communication between independent prefabs. Avoid wiring events directly between prefabs that are not in the same hierarchy, because that wiring is fragile to prefab restructuring and does not survive independent prefab instantiation.
• Configure AuthorityOnly to true on Effect Spawner hooks when the effect should be visible to all players. Client-local effects are only visible to the local player and produce confusion in multiplayer when other players cannot see them.
• Do not rely on the Collision Event Hook for client-side player detection in multiplayer. It only detects the local player on the client. For multiplayer-visible player detection, use server-authoritative hooks and broadcast the result through NPC Global Event Messenger.
• Leave UnityEvents.Allow_Client_Commands disabled on production servers unless a specific mod requires it. Enabling client-side command execution broadens the attack surface for potentially malicious Workshop mods. Prefer Server Text Chat Messenger for command execution when the command should be server-authoritative.
• Document the hook wiring for each prefab in the mod project's internal documentation. Hook wiring is stored in Unity's serialized scene and prefab data and is not human-readable in text form; without documentation, the wiring logic is invisible to anyone who did not configure it, including the original author returning to the project after an absence.
• When chaining multiple hooks on the same GameObject, order the hook components in the Inspector in the sequence they should fire. While the Inspector order does not strictly determine execution order (UnityEvent wiring order does), the visual arrangement aids in understanding and debugging the chain.
• Use Server Text Chat Messenger for announcements that all players should see and Client Text Chat Messenger for messages that are specific to the player who triggered the hook. The server-side messenger is the correct tool for global announcements, and the client-side messenger is correct for per-player feedback messages.

Frequently asked questions

Can I create my own custom Mod Hooks?

No. Only Mod Hook scripts that exist in the base game's C# assembly will be loaded from asset bundles. A mod developer cannot write a custom hook script, compile it, and export it in a bundle. The hooks that are available are limited to the set that the game developers have chosen to ship and maintain. Custom behavior that falls outside the available hook set requires server-side plugin development through the Unturned Dedicated Server API or through the OpenMod framework.

Can one GameObject have multiple Mod Hooks attached?

Yes. A single GameObject can carry any number of Mod Hook scripts, and the hooks operate independently. A common pattern is to attach a Collision Event Hook, a Timer Event Hook, and an Item Spawner to the same trigger-volume GameObject. The collision event starts the timer, and the timer's expiry event spawns the item, creating a delayed loot spawn when a player enters the trigger. There is no limit to how many hooks can coexist on one GameObject, though the Inspector can become difficult to navigate with more than approximately five hook components on a single object.

Do Mod Hooks work in singleplayer?

Yes. Every Mod Hook functions in singleplayer. Hooks that are documented as "server only" (such as Text Chat Event Hook and Collision Damage) function in singleplayer because the singleplayer host is both the server and the client. The "server only" designation means the hook is server-authoritative and does not fire on remote clients in multiplayer; in singleplayer, the host fulfills both roles, so the hook fires.

What happens if I wire an event to a method that does not exist at runtime?

The UnityEvent system validates method references at edit time in the Unity Editor. If the wired method exists on the target component when the event is configured, the reference is serialized in the prefab data. If the target component or method is removed from the GameObject before the bundle is exported, the event slot clears automatically. At runtime, if a wired method reference cannot be resolved (which should not happen if the prefab was exported correctly), Unity logs a warning to the console but does not crash and does not prevent other wired methods in the same event slot from executing.

Can Mod Hook events be wired across different prefabs?

Events can only be wired to GameObjects within the same prefab hierarchy or scene. You cannot wire a hook event on one prefab to a method on a different prefab that is not a child or sibling in the hierarchy at edit time. To coordinate behavior across multiple independent prefabs, use the NPC Global Event Hook and NPC Global Event Messenger system, which provides a decoupled pub-sub mechanism based on string event IDs that works across any prefabs in the loaded scene.

What is the difference between the Useable Event Hook and the Useable Gun Event Hook?

The Useable Event Hook fires for any EquipableItem prefab regardless of item type -- melee weapons, guns, throwables, consumables, and any other item that can be equipped. The Useable Gun Event Hook fires specifically for gun items and exposes gun-specific events (fire, reload, aim) that the generic hook does not provide. For a gun mod, use the Useable Gun Event Hook when you need gun-specific events and the Useable Event Hook when you only need generic equip, dequip, or use events.

Why does the Collision Event Hook only detect the local player on the client?

The Collision Event Hook only reports collisions with colliders on the Player layer (layer 9). On the client, only the locally-controlled character is on the Player layer; other connected players' characters are on the Enemy layer (layer 10). Because the hook cannot detect Enemy-layer collisions, a trigger volume on the client detects only the local player. On the server, all player characters are on the Player layer, so the hook detects all players. This is documented in the official SDG documentation as a known limitation. See Unity Layers Reference for the full layer configuration.

Can I use the Client Text Chat Messenger to execute any command?

The Client Text Chat Messenger can only execute commands if the UnityEvents.Allow_Client_Commands setting is enabled in the server configuration. This setting defaults to disabled on dedicated servers for security reasons. Even when enabled, commands are executed with the permissions of the player who triggered the hook, not with elevated server privileges. The cohort recommendation for Workshop mods is to use Server Text Chat Messenger for command execution where possible, because server-side command execution does not require per-server configuration and carries fewer security implications.

How do the Crafting Tag Provider and Crafting Tag Modifier work together?

The Crafting Tag Provider is attached to an entity (barricade, structure, vehicle, resource, or object) and defines a radius around that entity within which players can receive crafting tags. The Crafting Tag Modifier is a separate component that links to a provider and specifies which crafting tag to add or remove from the provider's available tags, under what activation conditions. The vanilla Heat Source system uses these two components: the campfire barricade has a Crafting Tag Provider, and a linked Crafting Tag Modifier with activation requirement Invert and mode Remove removes the Heat Source tag when the fire is extinguished. Together, these two hooks allow any entity type to function as a crafting workstation for any recipe category.

What is the Repeat hook useful for?

The Repeat hook is a general-purpose iteration mechanism for UnityEvents. Its primary use is to multiply a single event invocation into multiple invocations. A single Item Spawner.Spawn call spawns one item; wiring it through a Repeat hook with count 10 spawns ten items. A single Effect Spawner.Spawn call spawns one effect; wiring it through Repeat with count 5 spawns five effects in sequence. The Repeat hook is also used with a random count range to produce a variable number of spawns: count 3 to 8 produces between three and eight invocations per trigger.

Are Mod Hooks available for all game object types?

Mod Hooks can be attached to any GameObject in a prefab hierarchy that is exported in an asset bundle. The hooks are not restricted to specific entity types. However, some hooks only make sense on specific entity types: the Vehicle Event Hook requires a vehicle GameObject to produce its events; the Gun Attachment Event Hook requires a gun prefab; the Useable Event Hook requires an EquipableItem prefab. Attaching a hook to a GameObject that does not receive the trigger conditions the hook listens for is harmless but produces no events. The hook components themselves do not validate the GameObject type; they simply listen for conditions that may or may not occur on that GameObject.

Working with hook events that carry parameters

Some Mod Hook events carry parameters that provide context about the event: the player who entered a trigger, the attachment item that was attached to a gun, the vehicle that was entered. These parameters are available in the UnityEvent wiring dropdown as dynamic method arguments. When wiring an event that carries a parameter, the function dropdown shows methods that accept the appropriate type.

For example, the Vehicle Event Hook's OnDriverEntered event carries a Player reference. When adding a wired method to this event, methods that accept a Player parameter appear in the dropdown alongside methods that accept no parameters. If a method that accepts the parameter is selected, the parameter is passed automatically at runtime; no additional configuration is needed in the Inspector. If a method that does not accept the parameter is selected, the parameter is discarded and the method is called with no arguments.

The following table documents which listener hooks carry event parameters and what type each parameter conveys:

Hook	Event	Parameter type	What it carries
Collision Event Hook	OnPlayerEnter, OnPlayerExit	Player reference	The player who entered/exited the trigger
Gun Attachment Event Hook	OnAttached, OnDetached (all five types)	Item reference	The attachment item that was attached/detached
Vehicle Event Hook	OnDriverEntered, OnDriverExited	Player reference	The player who entered/exited the vehicle
Text Chat Event Hook	OnMessageMatched	String	The chat message that matched the filters
IOBS Event Hook	OnStateChanged	State enum	The new state of the IOBS

Instigator hooks that accept parameters through their wired methods (such as the Item Spawner's item ID or the Effect Spawner's spawn position) expose those parameters as configurable fields in the event slot after the method is selected, rather than receiving them dynamically from the calling event.

How to design a hook-driven mod feature from scratch

The following design workflow is the cohort-validated approach for planning a new hook-driven mod feature before opening the Unity Editor.

1. Define the desired player experience in one sentence: "When the player enters the boss arena, the doors lock, a warning message broadcasts, and the boss vehicle spawns after a five-second countdown."
2. Identify the trigger condition: what game event starts the chain? In this case, the player entering a trigger volume, which maps to a Collision Event Hook.
3. Identify the sequence of actions: door lock (GameObject activation), message broadcast (Server Text Chat Messenger), countdown (Timer Event Hook), boss spawn (Vehicle Spawner).
4. Identify the authority context for each step: door lock should be visible to all players (server-authoritative), message should be visible to all players (server-authoritative), countdown should be autoritative (server), boss spawn must be server-authoritative.
5. Map each step to the specific hook type: Collision Event Hook → GameObject.SetActive for doors, Server Text Chat Messenger for message, Timer Event Hook for countdown, Vehicle Spawner for boss.
6. Plan the event wiring chain: Collision Event Hook.OnPlayerEnter → door GameObject.SetActive(true), Server Text Chat Messenger.Broadcast, Timer Event Hook.StartTimer(duration 5). Then Timer Event Hook.OnTimerExpired → Vehicle Spawner.Spawn.
7. Implement the wiring in Unity, test in Play mode, build the bundle, and test in-game.

This design process ensures that every step in the feature chain is mapped to an available hook type before any work begins, which prevents the common scenario of designing a feature and then discovering partway through implementation that no hook type can provide the required trigger or action.

Hook performance considerations

Mod Hooks are lightweight components that add minimal runtime overhead when idle. A hook that is waiting for its trigger condition (a Collision Event Hook waiting for a player to enter its trigger, a Weather Event Hook waiting for a weather transition) consumes negligible CPU time because it subscribes to an existing game event rather than polling. Hooks that perform continuous checks (the Collision Damage hook checking for player overlap every tick) have a small but measurable per-frame cost that scales with the number of active hooks of that type.

The following performance guidelines are the cohort-validated recommendations for mod projects with large numbers of hooks:

Guideline	Rationale
Limit continuous-check hooks (Collision Damage) to a few dozen per scene	Each continuous-check hook evaluates its condition every frame. Large numbers of these hooks can accumulate into measurable frame-time cost.
Prefer event-driven hooks over timer-polling patterns	Event-driven hooks (Collision Event Hook, Weather Event Hook, Destroy Event Hook) consume zero CPU until their trigger condition occurs. A timer-based polling pattern using Timer Event Hook in a loop consumes CPU on every timer tick.
Use NPC Global Event Messenger for one-to-many communication instead of wiring the same event to many spawners	A single event broadcast can trigger dozens of NPC Global Event Hook listeners without additional wiring complexity or per-listener overhead beyond the UnityEvent invocation.
Remove hooks from prefabs that are destroyed and not re-instantiated	A hook on a destroyed-but-not-collected GameObject may continue to consume resources if the hook subscribes to global events. The OnDestroy lifecycle message cleans up most subscriptions, but explicit cleanup through disabling the hook component before destruction is a defensive practice for long-running server instances.

For the vast majority of mod projects, hook performance is not a constraint. The guidelines above become relevant only for large-scale mods with hundreds of interactive objects in a single scene, such as custom maps with extensive hook-driven scripting throughout the environment.

How hook behavior differs between singleplayer and dedicated server

The singleplayer environment masks several hook behaviors that become apparent only when the mod is loaded on a dedicated server with multiple connected clients. The following table documents the specific behavioral differences that the cohort has observed and validated across multiplayer testing.

Behavior	Singleplayer	Dedicated server
Collision Event Hook player detection	All players detected (only one player exists)	All players detected on the server; only local player detected on each client
Client Text Chat Messenger command execution	Enabled by default (server config defaults to on for singleplayer)	Disabled by default (must be explicitly enabled in server configuration)
Server Text Chat Messenger command execution	Enabled by default	Disabled by default (must be explicitly enabled in server configuration)
Effect Spawner with AuthorityOnly false	Effects spawn once (single host)	Effects spawn once per connected client, potentially producing N copies of the effect
Text Chat Event Hook	Fires for the host's chat messages	Fires for any player's chat messages that match the filters
Vehicle Event Hook	Fires for the host entering/exiting	Fires for any player entering/exiting on the server instance
Useable Gun Event Hook	Fires for the host's weapon actions	Fires for any player's weapon actions on their respective client instances

The cohort recommendation for mod developers publishing to the Steam Workshop is to test every hook-driven feature on a dedicated server with at least two connected clients before publication. Singleplayer testing is sufficient for initial development and hook wiring validation, but the multiplayer behavior differences documented above can produce bugs that are invisible in singleplayer and immediately apparent to the first player who joins a multiplayer server with the mod installed.

Appendix A: Mod Hook quick-reference card

Category	#	Hook name	Trigger / action	Fires on
Listener	1	Activation Event Hook	GameObject enabled/disabled	Server + Client
Listener	2	Binary Random Component	Triggered by another event; fires OnTrue or OnFalse randomly	Server + Client
Listener	3	Collision Damage	Player overlaps trigger; damages player	Server
Listener	4	Collision Event Hook	Player overlaps trigger; fires OnPlayerEnter/Exit	Primarily server
Listener	5	Destroy Event Hook	GameObject destroyed	Server + Client
Listener	6	Explosion Spawner	Triggered by event; applies damage in sphere	Server
Listener	7	Gun Attachment Event Hook	Sight/tactical/grip/barrel/magazine attached or detached	Server + Client
Listener	8	Interactable Object Binary State Event Hook	IOBS state changes (open/close, on/off)	Server + Client
Listener	9	Interactable Object Quest Event Hook	Quest interactable (Dropper/Note/Quest) successfully used	Server (authority)
Listener	10	NPC Global Event Hook	NPC Event with matching ID broadcast	Server + Client
Listener	11	Text Chat Event Hook	Chat message passes channel/radius/phrase filters	Server only
Listener	12	Timer Event Hook	Timer expires	Server + Client
Listener	13	Useable Event Hook	Item equipped/dequipped/used (any item type)	Server + Client
Listener	14	Useable Gun Event Hook	Gun fired/reloaded/aimed (supersedes Vehicle Turret Event Hook)	Server + Client
Listener	15	Vehicle Event Hook	Driver enters/exits vehicle	Server + Client
Listener	16	Vehicle Gear Shift Event Hook	Gearbox enters/exits target gear	Server + Client
Listener	17	Vehicle Health Event Hook	Vehicle health passes comparison threshold	Server + Client
Listener	18	Vehicle Turret Event Hook	Turret gun fired (superseded by Useable Gun Event Hook)	Server + Client
Listener	19	Weather Event Hook	Day/night/full moon/weather transition	Server + Client
Listener	20	Custom Weather Event Hook	Custom weather asset begins/ends	Server + Client
Instigator	1	Airdrop Spawner	Calls in an airdrop (optional cargo/destination override)	Server
Instigator	2	Barricade Spawner	Places a barricade at configured position	Server
Instigator	3	Client Text Chat Messenger	Sends chat message or executes command as client	Client (requires server config)
Instigator	4	Item Spawner	Spawns dropped item at configured position	Server
Instigator	5	Server Text Chat Messenger	Broadcasts chat message or executes command from server	Server (requires server config)
Instigator	6	Effect Spawner	Spawns effect asset (optionally AuthorityOnly)	Server or Client
Instigator	7	Mob Alert Spawner	Startles animals and zombies in radius	Server
Instigator	8	NPC Global Event Messenger	Broadcasts NPC Event with specified ID	Server
Instigator	9	Vehicle Spawner	Spawns vehicle (optional paint override)	Server
Misc	1	Barricade Destroyer	Removes barricades in sphere (optional effects/drops)	Server
Misc	2	Fall Damage Override	Overrides fall damage multiplier when landing on object	Server + Client
Misc	3	Crafting Tag Provider	Provides crafting tag radius (barricade/structure/vehicle/resource/object)	Server
Misc	4	Crafting Tag Modifier	Adds/removes specific crafting tag under activation condition	Server
Misc	5	Music Audio Source	Routes sibling AudioSource through music mixer	Client
Misc	6	Repeat	Repeats a UnityEvent N times (configurable or random count)	Server + Client

Appendix D: Hook selection guide by desired outcome

The following table is a reverse-lookup reference organized by what the mod developer wants to achieve, pointing to the hook or hook combination that implements it.

Desired outcome	Primary hook(s) to use	Notes
Open a door when a player approaches	Collision Event Hook → door GameObject activation	Use Timer Event Hook for auto-close
Spawn loot when an object is destroyed	Destroy Event Hook → Item Spawner	Add Binary Random Component for randomized drops
Create a damage zone (lava, radiation)	Collision Damage	Requires trigger collider; server-authoritative
Make a chat command trigger a world event	Text Chat Event Hook → instigator hooks	Server only; configure secret phrase
Create a day-night cycle reactive light	Weather Event Hook → light component activation	Wire OnDay and OnNight separately
Call an airdrop when a puzzle is solved	IOBS Event Hook → Airdrop Spawner	Wire after state-change event
Make a gun react to attachment changes	Gun Attachment Event Hook → visual effects	Separate events for each attachment type
Create a multi-phase boss encounter	Vehicle Health Event Hook → NPC Global Event Messenger → remote NPC Global Event Hook listeners	Phase transitions broadcast globally
Spawn a vehicle when a button is pressed	IOBS Event Hook or Collision Event Hook → Vehicle Spawner	Configure spawn position relative to hook
Play custom music at a location	Music Audio Source	Routes through player's music volume
Create a soft-landing surface	Fall Damage Override	Set multiplier 0.0 for no damage
Make a crafting station conditional on power	Activation Event Hook → Crafting Tag Modifier	Use Invert activation for powered-off removal
Clear all barricades in an area	Barricade Destroyer	Optional explosion effects and item drops
Startle zombies when a player makes noise	Mob Alert Spawner	Configure radius and player-as-origin
Broadcast a global message to all players	Server Text Chat Messenger	Requires server config enabled
Run a sequence of events with delays	Chain multiple Timer Event Hook components	Each timer's expiry starts the next
Repeat an action N times	Repeat	Random count range available for variation
Detect when a specific gear is engaged	Vehicle Gear Shift Event Hook	Configure target gear index
Respond to a custom weather type	Custom Weather Event Hook	Reference a custom Weather Asset

Appendix E: Debugging hook event chains

When a hook-driven feature does not work as expected, the following systematic debugging approach isolates the broken link in the event chain:

1. Start at the trigger: confirm the trigger condition is actually occurring. For a Collision Event Hook, walk the player character into the trigger volume and confirm the trigger collider is the correct size and on a layer that collides with the Player layer. For a Destroy Event Hook, confirm the GameObject is actually being destroyed.
2. Verify the hook component is present and enabled on the GameObject. An enabled hook shows its checkbox checked in the Inspector; a disabled hook does not fire events.
3. Temporarily wire the hook's event to a simple, visible action (such as GameObject.SetActive on a brightly colored test cube) to confirm the event fires at all. If the simple action works, the problem is downstream in the wiring chain.
4. For each downstream hook in the chain, verify that the method being called is the correct method name and that the parameters match. A misnamed method or a mismatched parameter type silently fails at runtime.
5. For instigator hooks (Item Spawner, Effect Spawner, etc.), confirm the item ID, effect asset reference, or spawn position is valid. An invalid item ID produces no spawn and no error message.
6. Check the game's log file for UnityEvent-related warnings. While most hook failures are silent, some produce log messages that identify the failed method or component reference.

This debugging approach is faster than trial-and-error rewiring because it systematically narrows the search space to the specific link in the chain that is failing, rather than requiring the developer to guess which hook or wiring is incorrect.

Appendix F: The NPC Global Event system as a decoupled communication layer

The NPC Global Event Hook and NPC Global Event Messenger pair forms a decoupled publish-subscribe event system that operates independently of the Unity prefab hierarchy. This system is the recommended mechanism for coordinating behavior across multiple independent prefabs, across multiple asset bundles, and across multiple locations in a map.

The system works on string-based event IDs. An NPC Global Event Messenger broadcasts an event with a specific ID string (for example, "boss_defeated"). Every NPC Global Event Hook in the loaded scene that is configured with the matching event ID fires its UnityEvent in response. The hooks do not need to be in the same prefab, the same bundle, or even the same folder as the messenger. They only need to share the same event ID string.

The following design pattern is the cohort-validated approach for multi-prefab coordination through the NPC Global Event system:

1. Define a naming convention for event IDs that includes a namespace prefix to avoid collisions with other mods. For example, "mymod_boss_phase_2" rather than "boss_phase_2". The namespace prefix prevents a hypothetical second mod from accidentally triggering your mod's hooks by broadcasting an event with the same ID.
2. Designate one "orchestrator" prefab that contains the NPC Global Event Messenger and the trigger logic that fires it. The orchestrator is typically a controller GameObject in the map that detects the game condition that should broadcast the event (a boss health threshold, a puzzle completion, a timer expiry).
3. Designate "responder" prefabs that contain NPC Global Event Hook components configured with the event IDs they should respond to. Each responder contains the visual, audio, or gameplay effects that should occur when the event is broadcast.
4. Test the event ID strings for exact character match. Event IDs are case-sensitive, and a single-character difference ("boss_phase_2" versus "boss_phase2") prevents the hook from responding to the messenger's broadcast.

The decoupled architecture is more maintainable than direct event wiring across prefabs because adding a new responder to an existing event does not require modifying the orchestrator prefab. The new responder simply needs an NPC Global Event Hook configured with the existing event ID, and it will respond to broadcasts without any change to the orchestration logic.

This decoupling is the single most powerful architectural pattern in the Mod Hooks system, and it is the foundation of every large-scale hook-driven mod feature.

Limitations of the Mod Hooks system

The Mod Hooks system is the most accessible mechanism for adding behavior to mod content, but it has well-defined boundaries that mod developers should understand before committing to a hook-driven design.

No conditional branching in event chains. A UnityEvent fires all wired methods in sequence, and there is no mechanism within the event system to branch based on the result of a wired method. The Binary Random Component provides a probability-based branch, but there is no conditional check such as "only spawn the item if the player's health is below fifty percent." Complex conditional logic requires server-side plugin development.

No persistent state between hook invocations. Each hook invocation is stateless. A Timer Event Hook can remember that a timer is running, but no hook can accumulate a count of how many times an event has fired or track which player triggered it. If a mod feature requires counting event invocations across multiple triggers, the counting must be done externally through a server plugin.

No cross-client coordination beyond NPC Global Events. A hook on one client's instance of a prefab cannot directly communicate with the same hook on another client's instance of the same prefab. The NPC Global Event system is the only cross-prefab communication mechanism, and it relies on string-based event IDs without payload data beyond the event ID itself.

Hooks are tied to GameObject lifecycle. A hook stops functioning when its host GameObject is destroyed. A mod feature that must persist after the GameObject that triggered it is removed from the scene cannot be implemented with hooks alone. The feature must either keep the host GameObject alive or delegate persistence to a server plugin.

Limited to the hooks that ship in the base game. The hook set is finite and grows only when game updates add new hook types. If a mod feature requires a trigger condition or action that no existing hook provides, the feature cannot be implemented through the hook system and requires server-side development.

Understanding these limitations before designing a hook-driven feature prevents the common experience of building a feature concept that the hook system cannot support and discovering the gap only after significant design work has been invested.

What are the security implications of enabling UnityEvents.Allow_Client_Commands?

Enabling UnityEvents.Allow_Client_Commands allows any Mod Hook on a client to execute arbitrary server commands on behalf of that client. The most significant risk is that a malicious Workshop mod could include a hook that executes commands the server host did not intend to permit, such as commands that spawn items, change game rules, or modify player data. The risk is mitigated by the fact that commands execute with the permissions of the player who triggered the hook, not with elevated privileges, and by the fact that the server host must explicitly opt into the setting. The cohort recommendation is to audit any Workshop mod that requests this setting be enabled, to test the mod in a controlled environment before deploying to a production server, and to leave the setting disabled unless a specific, trusted mod requires it.

Can I use Mod Hooks to create a custom game mode?

Mod Hooks alone cannot create a full custom game mode because they lack the state management, player tracking, and conditional logic that a game mode requires. However, hooks can provide the trigger-and-response layer for a custom game mode whose logic runs in a server-side plugin. The plugin manages the game state (score tracking, round timing, team assignment), and hooks on map objects provide the interactive elements (trigger volumes for capture points, item spawners for power-ups, chat messengers for announcements). This architecture -- server plugin for logic, Mod Hooks for interaction -- is the cohort-validated pattern for custom game mode development in Unturned™.

Will my hook wiring survive a Unity version upgrade?

Hook wiring is stored in Unity's serialized prefab data, which generally survives Unity version upgrades intact. However, if a hook script's public API changes between game versions (a method is renamed, a parameter type changes, or a hook is removed), the wiring to that specific hook will break. After a Unity version upgrade and Project.unitypackage re-import, the cohort practice is to open each prefab that uses Mod Hooks, inspect every wired event slot, and confirm that the function dropdown still shows a valid method name rather than "Missing" or "No Function." Broken wiring must be re-wired before the bundle is re-exported.

How does the game verify that a Mod Hook script matches the base game?

When the game loads an asset bundle at runtime, it compares each MonoBehaviour script in the bundle against the base game's C# assembly by type name and namespace. If the bundle contains a script whose fully qualified type name matches a type in the base game's assembly, the script is loaded and its events are connected. If the type name does not match any base game type, the script component is stripped from the GameObject and a warning is logged. This verification ensures that only officially exported Mod Hooks can execute in the game, and it is the reason that custom hook scripts created by mod developers are silently ignored at runtime.

What is the recommended approach for organizing hooks in a large mod project?

For mod projects with dozens of interactive prefabs, the cohort-validated organization pattern is to maintain a project-level hook wiring document that records, for each prefab, which hooks are attached, which events are wired, and what each wiring chain accomplishes. The document serves as a wiring reference during development, a debugging aid when a hook-driven feature stops working, and an onboarding document for new team members. The document format that the cohort uses is a simple table with columns for Prefab Name, GameObject Path, Hook Type, Event Field, Target GameObject, Target Method, Parameter Value, and Purpose. Maintaining this document adds approximately five minutes per prefab to the development workflow and pays back many times that investment when debugging or onboarding.

Do hooks interact correctly with Unity's undo system?

Yes. Adding, removing, and configuring Mod Hook components is tracked by Unity's undo system. Ctrl+Z reverts hook additions, event wiring, and parameter changes. However, Unity does not track changes to the internal state of hook components that were made through the Inspector's context menu (such as invoking a method directly for testing). Those direct invocations are not undoable, but they also do not persist beyond the current Editor session.

How do I know if a new hook type has been added to the game?

New hook types are announced in the Unturned™ game update changelog, which is posted on the Steam community hub and on the official Smartly Dressed Games blog. New hooks also appear in the Unturned components menu in the Unity Editor after re-importing the updated Project.unitypackage from the latest game version. The cohort practice is to check the changelog for each game update that mentions "modding," "hooks," "Unity events," or "editor tools," because new hook types are typically mentioned alongside other modding-toolchain changes.

Can I use Mod Hooks with custom C# scripts that I compile separately?

Not directly through asset bundles, because custom scripts cannot be exported in bundles. However, a server-side plugin (compiled as a .dll and loaded by the server's plugin framework) can interact with Mod Hooks by accessing the hook components on GameObjects at runtime. The plugin can read hook parameters, invoke hook methods, and subscribe to hook events programmatically through the Unity scripting API. This pattern is used for advanced mods that need behavior beyond what the hook system provides but still want to leverage hooks for the parts of the feature that hooks support well.

What should I do if a hook event fires in the Editor but not in the built game?

This pattern is almost always caused by an authority context mismatch. The most common scenario is a hook that fires on both server and client in the singleplayer Editor but only fires on the server in a multiplayer build, and the wired effects are client-side only. Verify the hook's authority context in the reference tables in this article, and confirm that the wired target methods execute on the same authority side where the hook fires. If the hook is server-only and the effect must be visible to all clients, use Effect Spawner with AuthorityOnly enabled or broadcast through NPC Global Event Messenger to trigger client-visible effects.

Appendix B: Hook authority context summary

Authority context	Hook types	Behavior in multiplayer
Server only	Collision Damage, Text Chat Event Hook, Explosion Spawner, Airdrop Spawner, Barricade Spawner, Item Spawner, Mob Alert Spawner, NPC Global Event Messenger, Vehicle Spawner, Barricade Destroyer, Crafting Tag Provider, Crafting Tag Modifier	Events fire on the server instance only. Wired effects on the server instance execute. Client instances of the prefab do not fire these hooks.
Server + Client	Activation Event Hook, Binary Random Component, Destroy Event Hook, Gun Attachment Event Hook, IOBS Event Hook, NPC Global Event Hook, Timer Event Hook, Useable Event Hook, Useable Gun Event Hook, Vehicle Event Hook, Vehicle Gear Shift Event Hook, Vehicle Health Event Hook, Vehicle Turret Event Hook, Weather Event Hook, Custom Weather Event Hook, Fall Damage Override, Repeat	Events fire on every instance of the prefab, server and all clients. Wired effects execute on every instance.
Primarily server (client-limited)	Collision Event Hook	Events fire on both server and client, but on the client only the local player is detected.
Server-authoritative (config-required)	Client Text Chat Messenger, Server Text Chat Messenger	Events fire on the specified authority side, but the server configuration must have the corresponding UnityEvents.Allow_* setting enabled.
Client-side	Music Audio Source	Audio routing is per-client and does not involve the server.
Configurable	Effect Spawner	The AuthorityOnly field determines whether the effect spawns server-authoritatively (replicated to clients) or locally per client.

Appendix C: External references

Resource	URL	Notes
Smartly Dressed Games modding documentation	https://docs.smartlydressedgames.com/en/stable/	Official Mod Hooks documentation in Chapter 12.
Unturned on Steam	https://store.steampowered.com/app/304930/Unturned/	Game page; changelog notes announce new hook types as they are added in updates.
Unity Manual: UnityEvents	https://docs.unity3d.com/Manual/UnityEvents.html	How Unity's event system works; the wiring mechanism that Mod Hooks use.
Mod Hooks original proposal (VitaxaRusModding)	Referenced in the official SDG documentation	The GitHub issue that proposed and coined the Mod Hooks feature.
Mod Hooks Reference (this article)	/items/mod-hooks-reference	The canonical 57 Studios reference for all Mod Hook types and their usage.

Document history

Version	Date	Author	Notes
1.0	2026-07-26	57 Studios	Initial publication. Complete Mod Hooks reference covering all 21 event listeners, 9 event instigators, and 6 misc hooks with parameters, use cases, authority contexts, validated patterns, FAQ, and appendices.

Cross-references

• Unity Layers Reference, the previous article in this section; the Collision Event Hook and Collision Damage hooks depend on correct layer assignments for trigger detection.
• Upgrading Unity Version, the next article; Mod Hook scripts must be re-imported and prefabs must be re-exported after a Unity version upgrade.
• Master Bundle Export, the Unity bundling workflow; Mod Hook prefabs are exported through master bundles alongside other prefab assets.
• Project Folder Structure and GUIDs, the Unity project setup that imports the Mod Hook scripts from the Project.unitypackage.
• Smartly Dressed Games modding documentation, official Mod Hooks documentation, Chapter 12.
• Unturned on Steam, game page and community hub.