ScrapExo Documentation

Section 1 — Overview

ScrapExo is a tiered exosuit system for Rust. Players activate a powered exoskeleton that replaces their standard armor and provides enhanced combat, mobility, survivability, and drone support. The suit is powered by a battery and fuel system. All features scale across 5 configurable tiers.

Core Impacts:

• Equips a full multi-layer suit (NVG, diving tank, and other attire) that provides passive protection — all damage is absorbed by the suit's armor bar before your health is touched
• Provides enhanced movement speed on land, in water, and optionally in flight (Exothrust)
• Grants automated medical support (auto-syringe, auto-bandage)
• Provides climate control (heater/AC) to prevent cold/heat damage
• Includes a fire weapon (longsword variant) and a forcefield item as belt tools
• Tier 5 Exothrust supports an optional shoulder launcher that can lock and fire at major vehicle bosses such as Bradley APC and patrol helicopter
• Tiers 3-5 support autonomous combat/scouting drones with optional live camera viewing from the drone management panel
• Includes support for FloorFrameDoors, the companion plugin used to place horizontal doors in floor frames for drone docking hatches
• Optional CopyPaste integration can deploy a prebuilt ScrapExo charging base from a skinned Legacy Shelter item
• Enhanced HUD shows compass-style directional markers for threats, teammates, bases, charging stations, and waypoints, plus telemetry (ALT, AGL, SPD)
• Suit state persists across disconnects and is restored on reconnect

What This Replaces

ScrapExo replaces or supersedes the following vanilla Rust mechanics:

• Armor system — multi-layer suit (NVG, diving tank, and various wear items) stacked in clothing slots, providing passive resistance to damage and environmental hazards
• Healing items — auto-syringe and auto-bandage trigger automatically
• Temperature survival — built-in heater and AC manage climate passively
• Mobility enhancements — speed boost, flight, and swim improvements replace vanilla movement
• Combat support — autonomous drones replace the need for manual combat tools

ScrapExo functions as a full gameplay system layer rather than a standalone utility plugin, integrating combat, mobility, automation, and UI into a unified experience.

Quick Start

1. Run /exo1 (or /exo5 for full feature testing)
2. Wait for the startup sequence (~13 seconds) — movement is reduced to a slow crawl while the suit powers up
3. Press Ctrl + Space to enable Exothrust flight
4. Use W / A / S / D to fly, Space to ascend, Ctrl to descend
5. Press E to toggle altitude hold while flying
6. Use /exodrone to manage drones (Tier 3+) and the Camera button to view a selected drone's camera
7. Use /exorefill to refill battery and fuel instantly (if permitted)

Section 2 — Commands

Chat Commands (player)

Console Commands (player, UI-driven)

Console Commands (admin)

Section 3 — Permissions

Section 4 — Controls

General Exosuit Controls

Exothrust Flight Controls

Swimming Controls

Section 5 — Core Systems

5.1 Exosuit Activation System

Activation is a two-step confirmation process or instant via activation item:

• Confirmation: Run /exo# twice — the first press shows the resource cost, the second confirms and activates.
• Auto-Equip: Suit equips custom armor, saves original wear/belt, and locks slots.
• Startup: 13.5-second boot sequence with diagnostic messages. Speed boosts are removed during this window — you can still move but only at a slow unassisted pace.
• Alternative: Place a matching-skin metal.shield in the backpack slot.
• Deactivation: Run /exo# again for a 10-second shutdown sequence.

5.2 Armor System

The suit is made up of multiple layered wear items (NVG, diving tank, and other attire) all stacked into the clothing slots at once. Together they provide passive protection against damage and environmental hazards. The Armor Bar on your HUD represents the combined health of these layers — when it hits zero, the suit is destroyed. Your personal health is not affected as long as armor remains.

• All damage is absorbed by the armor bar before touching your health.
• Hit effects play on every strike. When the armor bar fully depletes, a debris burst effect always plays.
• Fall damage is reduced by 50% (default).
• If any bleeding occurs (e.g. during initial suit-up), it is automatically cleared within a fraction of a second.

5.3 Climate Control System

• Heater: Activates < 15°C, targets 32°C.
• AC: Activates > 38°C, targets 28°C.
• Drains: Battery.
• Cycle: 30-second minimum prevent rapid switching.

5.4 Speed / Movement System

The suit gives you a speed boost that scales up per tier. The game's built-in anti-cheat is suppressed to allow this enhanced movement without triggering false kicks.

5.5 Auto-Medical System

The suit monitors your health and automatically uses medical items from your inventory. This is most useful during the startup phase before the suit is fully powered on.

• Auto-Syringe: If your health drops below 50, the suit automatically uses a syringe from your inventory. Costs battery.
• Auto-Bandage: If bleeding is detected, the suit automatically applies a bandage. Costs battery. (Once the suit is fully active, bleeding is suppressed passively and auto-bandage acts as a backup safety net.)
• Cooldown: 10 seconds between auto-syringe uses, 5 seconds between auto-bandage uses.

5.6 Night Vision System

Tiers 2–5 F to enable night vision goggles when the suit activates. They are removed when the suit shuts down.

5.7 Fire Weapon System

A custom fire longsword is placed in your belt. It shoots heat projectiles that deal fire damage and can damage structures. Each shot consumes fuel.

5.8 Forcefield System

A forcefield item is placed in belt slot 2. When activated, it projects a visible protective sphere around you that absorbs incoming damage. The sphere flashes red whenever it takes a hit. Drains battery for the duration it's active. A small timer above the slot 2 forcefield item shows active time as FF, then cooldown time as CD.

5.9 Shoulder Launcher System

The shoulder launcher is an optional experimental Tier 5 Exothrust flight weapon feature. It has functional targeting and firing logic and is designed primarily for first-person use.

• Activation: Autofire is available only while Exothrust is active.
• Visuals: The shoulder launcher prefab can be shown or hidden with SpawnShoulderLauncherPrefab.
• Aiming visual: The launcher stays on a fixed left-shoulder mount, tracks pitch up/down, and uses limited yaw clamped to 18 degrees in either direction.
• Firing: Shoulder launcher autofire uses the active aim-assist lock, battery drain, and fire interval. Valid lock targets include normal aim-assist targets plus major vehicle bosses such as Bradley APC and patrol helicopter.
• Vehicle boss range: Bradley APC and patrol helicopter use AimAssist.VehicleBossRange for lock range, so aircraft can be locked farther away than normal players, NPCs, or animals.
• Note: The shoulder launcher is visually aligned for first-person gameplay. Third-person and spectator views may show offset positioning due to Rust player model limitations. This does not affect functionality.

Section 6 — Progression / Tiers

Section 7 — Drone System (Detailed)

7.1 Drone Behavior States

At any given time, each drone is in one of the following modes:

• Hovering: Orbiting around you, waiting for something to happen.
• Going to base: Heading to your selected base to recharge through the hatch or await orders.
• Holding at waypoint: Hovering in place above a saved waypoint until recalled.
• Returning to player: Flying back to you after a recall command.
• Landing / Ascending: Performing the hatch docking sequence — centering above the door and dropping in, or climbing back out after charging.
• Charging: Sitting on the DiscoFloor inside your base, refilling its battery.
• Chasing a target: Actively pursuing and attacking an enemy.
• Sync lost: Owner has disconnected — drone wanders until the player reconnects.

7.2 Drone Management Panel

Opened with /exodrone. Requires Tier 3+ exosuit. The panel has two columns: your authorized bases on the left and your saved waypoints on the right. During suit shutdown/deactivation, drone commands are locked until shutdown completes.

Drone Selector

A row of buttons appears at the top of the panel showing each active drone (D1, D2, D3...) plus an ALL button. Click a D# to target that specific drone for your next action. Click ALL to apply actions to every drone at once. Selecting a drone that is unavailable or destroyed shows a warning and keeps the current selection unchanged. Active drones tint their D# button by battery state: green at 70% or higher, yellow at 50% or higher, orange at 30% or higher, and red below 30%. A chat confirmation ([DRONE] Selected: D1) is sent each time you make a selection so you can verify what the system registered. Action buttons (Deploy, Recall, Recall All, Camera) have a short cooldown to prevent accidental double-firing from rapid clicks.

Actions

• Deploy to Target: Sends the selected drone(s) to whichever base or waypoint is highlighted yellow. Drones actively charging on their pad are protected and cannot be redirected — drones still in transit can be overridden immediately.
• Recall: Brings a specific selected drone (D1, D2...) back to you. Requires a D# to be selected — not available when ALL is active.
• Recall All: Brings every drone back to orbit around you and clears all base/waypoint assignments.
• Storage: Opens the selected drone's cargo inventory when a D# is selected, otherwise the first available drone is used. The opened drone lands beside the operator and stays grounded while the cargo panel is open, then resumes flight after the panel closes.
• Camera: Connects your view to the selected D# drone's camera. A specific drone must be selected first; ALL cannot be used for camera viewing. Pressing Camera again while viewing the same selected drone disconnects the camera. Selecting another D# and pressing Camera exits the current camera session first, then connects to the new drone after the temporary computer station cleanup completes. Charging drones cannot be viewed until they are airborne again.
• Spawn: Spawns a new drone. Without scrapexo.bypass.drone, a drone item is consumed from your inventory. With the bypass permission, drones are free to spawn. Shows a warning if no item is available or permission is missing. Alternatively, dropping a drone item from your inventory while the suit is active will also spawn it directly. If the chassis has a depleted battery, you must be standing within 3m of a powered charging station — the drone will spawn directly onto the pad and begin charging at the normal rate, activating automatically once full. Safety lock: spawn from panel and drop-to-activate are both blocked while suit shutdown/deactivation is active.
• Despawn: Recalls all active drones. Each drone flies back to your position, lands nearby, then returns its chassis to your inventory. Players with scrapexo.bypass.drone have their drones simply deactivate on landing — no item is returned since none was spent.

Waypoints in the Panel

Waypoints saved with /wpmark appear in the right column of the drone panel. Selecting one and clicking Deploy to Target sends the selected drone(s) there. Drones circle above the waypoint until recalled — they do not automatically return on their own unless battery depletes. Waypoint marking ignores window, embrasure, and shutter prefabs so operators can mark terrain or targets through base viewing ports.

7.3 Charging Behavior (Hatch Docking)

1. When a drone's battery is low (<30), it diverts to a charging station if one is in range.
2. It navigates to the floor-frame hatch above the charging area, aligns itself over the opening, and opens the hatch.
3. The drone descends through the hatch into the base interior, moves to an available DiscoFloor charging pad, positions itself correctly, and begins charging.
4. After reaching full battery, it ascends back through the hatch and returns to the last active assignment, such as a waypoint or base hover position. If no assignment is stored, it returns to normal player hover.

FloorFrameDoors companion plugin: Drone hatch docking is designed around floor-frame doors created by the included FloorFrameDoors.cs plugin. FloorFrameDoors adds an invisible wall-frame proxy to floor frames so normal Rust doors and double doors can be placed horizontally as hatch doors. ScrapExo recognizes those horizontal doors and uses them as drone entry/exit points above charging rooms.

If multiple drones return at the same time, they queue their entry — each drone waits until the hatch and charging area are clear before proceeding to avoid collisions.

If more than one valid pad is available, drones prefer pads that the owner is not currently standing on. A player-occupied pad is used only as a fallback when no better powered/authed pad has an available drone slot.

Low-battery drones cancel current travel tasks (base/waypoint/chase) and divert to charging. If no charging station is available, the drone returns to the operator for retrieval.

If a drone reaches 0 battery before retrieval, it crashes in-world (no instant inventory teleport). The suit console reports the grid and relative direction from the operator at signal loss.

Drone cargo stays on the drone during normal battery-0 crashes or emergency landings. Cargo only moves into a wooden loot box when the drone is truly destroyed, such as being shot down.

Lost-drone tracking above the armor bar is intentionally disabled; operators rely on the console warning/grid callout for recovery.

Battery state is remembered. When a drone is retrieved its remaining battery level is stored on the chassis item. A drone returned with a depleted battery can only be reactivated by standing within 3m of a powered charging station and using Spawn or dropping the item — the chassis will be placed directly on the pad and charge at the normal rate before automatically taking off.

Depleted spawn behavior: If a spawned chassis has too little battery to fly and the player is standing on a powered charging station, the drone stays on the charging pad instead of taking off and immediately landing again. The station check uses the pad footprint instead of a broad nearby radius so adjacent pads are less likely to trigger accidentally.

Important: DiscoFloor charging pads require an active power source to function. Charging drones and the exosuit both draw from connected batteries — make sure your base power supply is sufficient to support both.

7.4 Drone Camera View

The drone panel includes a Camera button for viewing through a selected drone. Select a specific D# first, then click Camera. The plugin creates a temporary hidden computer-station controller behind the scenes, links it to the drone, and mounts the player into the camera feed.

• Connection: Requires an active, available D# drone. Destroyed, unavailable, charging, or ALL selections are rejected with chat feedback.
• Switching: While viewing one drone, select a different D# and press Camera to disconnect the old feed, clean up the temporary station, and then connect to the new one. Pressing Camera on the same selected drone toggles the camera off.
• Exit: Use the camera Exit button to disconnect from the drone view. The plugin also removes the temporary station and restores the normal HUD layout when the camera session ends.
• Manual look: While the drone is hovering and not in combat, mouse movement rotates the drone camera/drone facing direction. When the drone engages a target, combat AI takes rotation control. When combat ends, manual camera rotation is available again.
• Camera HUD: Radar, custom bars, telemetry, and Enhanced HUD are rebuilt into camera-safe positions while viewing a drone, then restored to the normal layout after disconnect.

Section 8 — Resource Management

8.3 Charging Station (DiscoFloor)

Standing on a DiscoFloor recharges your suit battery. Higher tiers charge faster. You need to be standing directly on the floor footprint to get the charge — hovering just above it or standing beside it won't count. This tighter footprint check helps prevent adjacent pads from triggering when the player is not actually on that pad.

Charging pad color/state is refreshed for authorized players within 100m. This helps clients see the correct ready, cooldown, or charging color when returning to a base after the pad changed state while they were away.

Deployment: Players can deploy their own charging stations by placing a Disco Rug (Skin 10006). Upon placement, the rug is automatically converted into a functional DiscoFloor entity. These can be distributed via Kits or other item spawning plugins.

Section 9 — UI / HUD

9.1 Status Bars

Armor, Battery, and Fuel bars on left. Auto-shift upward to avoid overlapping vanilla status effects.

9.2 Enhanced HUD (Tiers 3–5)

Compass updated every 1s. Markers for Drones (Yellow), Charging Stations (Cyan), Threats (Red), Teammates (Green), Base, and Waypoints.

The radar also shows major vehicle boss targets such as Bradley APC and patrol helicopter as larger orange contacts so they stand out from normal hostile dots. These same vehicle boss types can be used by Tier 5 target lock and shoulder launcher firing.

9.3 Telemetry Panel

• [ALT]: Altitude (MSL).
• [AGL]: Height via raycast (Color-coded: Red < 10ft, Yellow < 30ft).
• [SPD]: Speed (Color-coded: Cyan > 3m/s, Orange > 10m/s).

9.4 Drone Camera HUD Mode

When connected to a drone camera, ScrapExo temporarily rebuilds the HUD into a camera-safe layout. The camera view uses its own positions for the radar, custom armor/battery/fuel/drone bars, telemetry, Enhanced HUD, and camera Exit button so they do not sit under the default Rust computer-station UI. On disconnect, the normal player HUD layout is restored.

Section 10 — Skinned Items (IDs)

The following custom skins are used by the plugin to identify special items. Server owners can use these IDs with plugins like Kits or Give to distribute items to players.

Note: You can use plugins like Kits to assign these skinned items to starter kits or rewards, allowing players to deploy their own Disco Floor charging stations by placing the Disco Rug.

Optional CopyPaste integration: The Exo Base Deployer runs the equivalent of paste exobase a true s true at the shelter placement position. ScrapExo authorizes the deploying player on pasted tool cupboards and limits each player to one active deployed Exo Base. The one-base limit is checked before paste begins and also blocks pending deployments to prevent spam placing. If CopyPaste is missing, the paste file is missing/broken, the paste fails, or no entities spawn, the shelter is refunded and the player is notified. Missing CopyPaste uses this message: CopyPaste is required to deploy Exo Bases.

Section 10.5 — Localization (Multi-Language Support)

All player-facing chat and console (drone/suit) messages route through the standard Carbon/Oxide lang API. The English message file is auto-generated on first load.

File Location

• English (default): oxide/lang/en/ScrapExo.json (or carbon/lang/en/ScrapExo.json on Carbon)
• To add another language, copy the en/ScrapExo.json file to lang/<locale>/ScrapExo.json (e.g. de, fr, es-ES, pt-BR, ru) and translate the values. Keys must remain unchanged.
• The plugin uses each player's selected language automatically. Missing keys fall back to English.

Key Categories

• Cmd.* — Chat command responses (help text, permission errors, waypoint feedback, refill, item grants).
• Suit.* — Exosuit activation, cooldown, lockout, fuel/battery transfer, forcefield, fire weapon, exothrust, resources updates.
• Drone.* — Drone power/charging, boot/shutdown diagnostics, medical scan, temperature, autonomous behavior (link recovery, ascent, mailbox, retrieval).
• Drone.Ui.* — Drone management panel button responses (deploy, recall, camera, spawn, despawn, base selection).
• Deploy.* — Exo Base Deployer messages.
• Status.* — Generic status words (READY, ONLINE, OFFLINE, STANDBY) used inside other localized boot/diagnostic messages.

Format Placeholders

Some messages use numbered placeholders such as {0}, {1:F0}, {2}. These must be preserved in translations — they are filled with runtime values (counts, percentages, names, grid references). The localization helper is crash-safe: a malformed placeholder will fall back to the unformatted message rather than throw an exception.

Out-of-Scope Strings

The following are intentionally not localized:

• CUI labels in the drone management panel and HUD overlays — kept in English to avoid layout breakage from variable string widths.
• Admin/debug output (e.g. exo.debug dump, debug-gated power-pad warnings) — server operator-facing only.
• Console (server) log lines via Puts / PrintWarning — operator-facing only.

Section 11 — QA Testing Checklist

• /exo lists tier commands and utility commands
• /exo1 confirms scrap deduction (no bypass)
• /exoitem1 gives metal.shield with skin
• Startup sequence (13.5s) — player moves slowly, speed boost absent until boot completes
• Armor absorbs damage before health
• Fall damage reduction applies
• Ctrl + Space toggles exothrust reliably (no double trigger)
• Shoulder launcher does not appear during normal suit activation
• Shoulder launcher visual follows SpawnShoulderLauncherPrefab
• Shoulder launcher can lock/fire at Bradley APC and patrol helicopter targets
• Patrol helicopter lock range uses AimAssist.VehicleBossRange and can exceed normal aim-assist range
• Radar shows Bradley APC and patrol helicopter as larger orange contacts
• E toggles altitude hold only during active flight
• Battery depleted — player moves slowly like unpowered heavy armor, no speed boost
• Battery drain stops when all systems are inactive
• Suit shutdown returns one battery and discharges overflow charge only into existing inventory batteries
• Fuel drains during fire weapon usage
• Drone spawns and enters hover/orbit
• Drone battery drains only while airborne (not while grounded/charging)
• Drone below charge threshold — immediately cancels current task (base travel, waypoint, etc.) and diverts to nearest charging station within 350m
• Drone low battery with no station in range — flies back to operator, lands nearby, chassis returned to inventory
• Drone battery hits zero before reaching charger or player — shuts down immediately and falls from sky; console log shows grid reference and direction from operator
• Drone actively returning to player (despawn/low battery) is NOT redirected to a charging station mid-flight
• Drone hatch docking sequence (ascend/descend through floor-frame hatch)
• FloorFrameDoors is loaded and horizontal floor-frame doors can be placed for drone hatch docking
• Exo Base Deployer requires CopyPaste and refunds the shelter if CopyPaste is missing
• Exo Base Deployer refunds the shelter if the exobase paste fails or spawns no entities
• Exo Base Deployer consumes the skinned shelter, pastes exobase, and authorizes the deploying player on pasted tool cupboards
• Exo Base Deployer blocks a second active Exo Base for the same player
• Multiple drones returning simultaneously — queue correctly, no collisions at hatch
• DiscoFloor requires active power source — charging stops if power is removed
• After full charge, drone ascends and returns to player
• Charging station beyond 350m — drone treated as no station found (returns to operator)
• Drone chassis retrieved with <31 battery — blocked from spawning if no station within 3m (error shown)
• Drone chassis retrieved with <31 battery — stand on powered station footprint, Spawn places it on pad and it charges normally then auto-activates
• Drone spawned with depleted battery near a powered station stays on the charging pad and does not take off until charged
• Active drone D# selector buttons update red/orange/yellow/green by battery level
• Adjacent charging pads do not trigger unless the player is on that pad's footprint
• Charging pad ready/cooldown/charging colors update for authorized players returning within 100m
• Drone chooses a powered/authed pad not occupied by the owner when another pad with a drone slot is available
• Drone retrieved with partial battery — respawns at that battery level (not full)
• Drone assigned to a waypoint returns to that waypoint after charging instead of defaulting back to player hover
• Camera button requires a specific D# selection and rejects ALL selection
• Camera button connects to selected drone camera, and pressing Camera again on the same D# disconnects
• Selecting another D# while in camera view and pressing Camera exits the old station first, then swaps to the new drone camera
• Camera Exit button disconnects view, removes temporary station, and restores normal HUD layout
• Mouse movement rotates the drone while hovering in camera view, but combat AI takes rotation control during target engagement
• Multiple players using suits simultaneously — no interference
• Telemetry (ALT/AGL/SPD) updates and colors correctly
• Suit state restores on reconnect
• Lang file lang/en/ScrapExo.json generated on first load and used for all player-facing chat/console messages
• Translated lang file in another locale (e.g. lang/de/ScrapExo.json) is picked up per-player based on client language

Section 13 — Technical Notes

Key Classes

• ExoData: Main per-player state container.
• ExoDrone: MonoBehaviour (16 Hz update) for drone AI.
• DroneCameraSession: Per-player camera session state for the temporary computer-station bridge used by drone camera viewing.
• ExothrustComponent: Physics handler for flight.
• MovableBaseMountable: Custom mountable to prevent dismounting.

Performance

• Content-hash caching for all UI redraws.
• Raycasts limited to 1 per second for Telemetry.
• Facepunch.Pool used for all entity lists.
• Drone camera sessions are tracked per player and cleaned up on disconnect, death, suit deactivation, plugin unload, or drone removal.

Companion Plugins

• ImageLibrary: Required for HUD/radar icons.
• FloorFrameDoors: Included companion plugin for placing horizontal doors in floor frames. Recommended for ScrapExo drone hatch docking and charging-room entry/exit behavior.
• CopyPaste: Optional integration used by the Exo Base Deployer. Requires a saved paste file named exobase.

Section 14 — Configuration Notes

Quick overview: Most gameplay behavior is configurable from the plugin config without code edits. You can tune balance, UI behavior, automation, and progression for your server style.

• Tier balancing: armor values, battery/fuel capacities, drain rates, speed multipliers, flight/swim boosts, and feature unlocks per tier.
• Drone systems: max drones per tier, chase/hover ranges, charging behavior, battery thresholds, and turret enable/scaling.
• Combat & survivability: forcefield settings, fire weapon behavior, healing automation, shoulder launcher visuals, and fall-damage handling.
• HUD/UI: radar, console, and bar behavior/positions; visibility rules; update cadence and status presentation.
• Resource economy: item costs, refill behavior, charging rates, and conversion/consumption pacing.
• Base deployment: optional ExoBaseDeployer settings control the skinned Legacy Shelter deployer, CopyPaste paste file name, authorization behavior, stability option, one-base-per-player limit, and CleanupDeployedBasesOnUnload. Cleanup on unload defaults to false.
• Admin controls: permissions, bypass rules, diagnostics/debug toggles, and command access boundaries.

Experimental Features (Optional)

• Tier 5 Shoulder Launcher system: Fully functional targeting and firing logic, designed primarily for first-person use.
• Visual toggle: Set SpawnShoulderLauncherPrefab to false to disable the shoulder launcher visual while keeping firing behavior controlled by the existing per-tier shoulder launcher settings.
• Vehicle boss lock range: AimAssist.VehicleBossRange controls long-range locking for Bradley APC and patrol helicopter. Normal aim-assist targets continue to use AimAssist.Range.
• View limitation: Third-person and spectator views may show offset positioning due to Rust player model limitations. This does not affect functionality.

Skin Ownership (UseSkinOwnership)

Controls how custom skins are applied to suit items (armor pieces, belt tools, etc.):

• true (recommended): Skins are only applied if the player owns them. Non-owned skins fall back to default appearance.
• false: Forces skins regardless of ownership. May not work with all DLC/paid skins and is not recommended.