RUST Spawn Modular Car v5.3.0

Features​

• Allows players with permission to spawn modular cars
• Each player may have one car at a time using the mycar command
• Cars may spawn ready to drive, depending on the plugin configuration and player permissions
• Supports multiple types of presets, including personal presets
• API and an admin/server command allow spawning unlimited cars with a variety of options

Quick start​

Use case #1: Allow players to spawn cars with the mycar command​

1. Grant the spawnmodularcar.spawn.4 permission to allow players to spawn a 4-socket car with the mycar command.
2. Check out the rest of the documentation to learn about additional features and options.

Use case #2: Allow players to create and manage their own presets​

1. Grant a permission such as spawnmodularcar.spawn.4 to allow players to spawn cars.
2. Grant the spawnmodularcar.presets permission to allow players to save and manage their own presets.
3. Read about the commands this enables in the Commands > Personal presets section of the documentation.

Use case #3: Allow admins to create and manage presets for the whole server​

1. Grant a permission such as spawnmodularcar.spawn.4 to allow players to spawn cars.
2. Grant the spawnmodularcar.presets.common permission to allow players to spawn cars from common presets.
3. Grant the spawnmodularcar.presets.common.manage permission to admins to allow creating and managing common presets.

This will allow:

1. Admins to save common presets with mycar common save <name>, as well as update and delete common presets with similar commands.
2. Players to spawn cars from a common preset with mycar common <name>.

Read more about the commands this enables in the Commands > Common presets section of the documentation.

Use case #4: Allow admins to spawn unlimited preset cars​

1. Update the ServerPresets section of this plugin's configuration to define one or more named presets.
2. Reload the plugin.
3. Grant the spawnmodularcar.givecar permission to admins.

This allows admins to use the givecar <player> <preset> command to spawn a car in front of the specified player using the specified preset. This can be done as many times as you want.

Use case #5: Allow players to spawn preset cars via other plugins such as GUI shop​

1. Update the ServerPresets section of this plugin's configuration to define one or more named presets for your players to purchase. See the Configuration > Server presets section for examples.
2. Reload the plugin.
3. Refer to the documentation for GUI shop or whichever plugin on how to configure a shop listing to call the givecar command. It may look something like givecar $player.id preset1.

Commands​

This plugin provides both chat and console commands using the same syntax. When using a command in chat, prefix it with a forward slash: `/`.

Spawn commands​

• mycar -- Spawn a modular car using your "default" preset if saved, else spawn a random car with the maximum number of allowed sockets based on your permissions.
• mycar <2|3|4> -- Spawn a random modular car with the specified number of sockets.
• mycar <name> -- Spawn a modular car from the specified personal preset. See the personal presets section for more details.
• mycar common <name> -- Spawn a modular car from a common preset managed by privileged adminstrators. See the common presets section for more details.
• givecar <player> <preset> -- Spawn a car for the target player using the specified server-wide preset. See the server presets configuration section for details.

When a modular car is spawned, it will be at full health. Additionally, depending on your granted permissions and personal settings:

• It may be fueled (amount is configurable).
• It may automatically have a code lock, via the Vehicle Deployed Locks plugin.
• It may automatically have a key lock, via the Vehicle Deployed Locks plugin.
• All tanker modules may be automatically filled with fresh water (amount is configurable).
• All engine modules may be automatically filled with your highest allowed quality of engine parts.

Other commands​

• mycar fix -- Fix your car. This restores it to original condition as though you had just spawned it, with the exception that it will not add or remove a lock, regardless of your AutoCodeLock or AutoKeyLock setting. Engine parts will also be repaired. If you were granted any of the spawnmodularcar.engineparts.* permissions, missing engine parts are added, and lower quality parts are replaced with the maximum quality you are allowed.
• mycar fetch -- Teleport your car to you in an upright position.
• mycar destroy -- Destroy your car, allowing you to spawn a new one.
  • Non-empty storage modules will drop a bag with their items next to where the car was located.
  • If the car's engine modules contained parts that are of higher quality than are allowed by your spawnmodularcar.engineparts.* permissions, those will be added to your inventory if there is space, else dropped to the ground in front of you.
• mycar help -- Print a list of available commands and their usage. Only shows commands allowed by your permissions.

Personal presets​

Players with the spawnmodularcar.presets permission can save custom module configurations, allowing them to spawn their car or change their car in-place with a saved preset.

• mycar list -- List your saved module configuration presets.
• mycar save <name> -- Save your car's current module configuration under the specified preset name.
• mycar update <name> -- Overwrite an existing preset with your car's current module configuration.
• mycar load <name> -- Load the specified preset (partial name matching supported) onto your existing car, replacing any modules that don't match the preset. Loading a preset is not allowed if your current car is occupied or if it has a different number of sockets than the preset.
  • The car will be fixed according to the same rules as mycar fix.
  • The car's locks will be removed if the car no longer has at least one cockpit module.
  • Non-empty storage modules that were replaced will drop a bag with their items next to the car.
  • Any engine parts of higher quality than are allowed by your spawnmodularcar.engineparts.* permissions will be redistributed throughout the engine modules in the loaded preset, with the highest quality parts towards the front-most engine modules. If any engine parts are left over, those will be added to your inventory if there is space, else dropped to the ground in front of you.
• mycar rename <name> <new name> -- Rename a preset.
• mycar delete <name> -- Delete the specified preset.

Note: The save, update, load and delete commands will use the "default" preset if the preset name is not specified.

Common presets​

Players with the spawnmodularcar.presets.common.manage permission can optionally save their cars as common presets for the rest of the server to use. Any player with the spawnmodularcar.presets.common permission can list common presets and spawn a car from a common preset, as long as the player's spawnmodularcar.spawn.* permission allows for the number of sockets in the preset.

• mycar common list -- List all common presets that you have permission to spawn, based on your spawnmodularcar.spawn.* permission.
• mycar common load <name> -- Load the specified common preset onto your existing car. See the personal preset section for details on how loading works.
• mycar common save <name> -- Save your car's current module configuration under the specified common preset name.
• mycar common update <name> -- Overwrite an existing common preset with your car's current module configuration.
• mycar common rename <name> <new name> -- Rename a common preset.
• mycar common delete <name> -- Delete the specified common preset.

Personal settings​

• mycar autocodelock -- Toggle AutoCodeLock. While ON, spawning your car will automatically create a code lock and add it to the front-most cockpit module if it has one. Requires spawnmodularcar.autocodelock permission.
• mycar autokeylock -- Toggle AutoKeyLock. While ON, spawning your car will automatically create a key lock and add a matching key to your inventory, as long as the car has at least one cockpit module. Requires spawnmodularcar.autokeylock permission.
• mycar autofilltankers -- Toggle AutoFillTankers. While ON, spawning your car, fixing it, or loading a preset will automatically fill any tanker modules to allowed capacity (configurable) with fresh water, replacing any salt water already in them. Requires spawnmodularcar.autofilltankers permission.

Permissions​

This plugin uses the permission system. To assign a permission, use oxide.grant <user or group> <name or steam id> <permission>. To remove a permission, use oxide.revoke <user or group> <name or steam id> <permission>.
The following permissions control the maximum number of module sockets the player is allowed to have on their car. If none of these are granted, the player cannot spawn a car, even from a preset.

• spawnmodularcar.spawn.2 -- Allows spawning a car with 2 sockets.
• spawnmodularcar.spawn.3 -- Allows spawning a car with 2-3 sockets.
• spawnmodularcar.spawn.4 -- Allows spawning a car with 2-4 sockets.

Granting the following permissions will cause the player's car to automatically spawn with engine parts of the corresponding quality in each engine module. If none of these are granted, the car spawns without any engine parts, so it cannot be driven until a player adds them.

• spawnmodularcar.engineparts.tier1 -- Spawn your car with low quality engine parts.
• spawnmodularcar.engineparts.tier2 -- Spawn your car with medium quality engine parts.
• spawnmodularcar.engineparts.tier3 -- Spawn your car with high quality engine parts.

Presets:

• spawnmodularcar.presets -- Allows you to spawn your car from a personal preset. Also enables the save, update, rename and delete preset commands.
• spawnmodularcar.presets.load -- Required to use mycar load <preset> and mycar common load <preset>.
• spawnmodularcar.presets.common -- Required to use mycar common <preset> and mycar common load <preset>.
• spawnmodularcar.presets.common.manage -- Required to manage common presets.
• spawnmodularcar.givecar -- Required to use the givecar command.

Misc:

• spawnmodularcar.fix -- Required to use mycar fix.
• spawnmodularcar.fetch -- Required to use mycar fetch.
• spawnmodularcar.despawn -- Required to use mycar destroy.
• spawnmodularcar.autofuel -- Fuels your car automatically.
• spawnmodularcar.autocodelock -- Required to use the automatic code lock feature (i.e., mycar autocodelock).
• spawnmodularcar.autokeylock -- Required to use the automatic key lock feature (i.e., mycar autokeylock).
• spawnmodularcar.autofilltankers - Required to use automatic filling of tanker modules (i.e. mycar autofilltankers).
• spawnmodularcar.autostartengine -- Start your car's engine instantly.

Configuration​

The settings and options can be configured in the SpawnModularCar file under the config directory. The use of an editor and validator is recommended to avoid formatting issues and syntax errors.

• CanSpawnWhileBuildingBlocked (true or false) -- Whether to allow players to spawn their car while they are building blocked.
• CanFetchWhileBuildingBlocked (true or false) -- Whether to allow players to fetch their car while they are building blocked.
• CanFetchWhileOccupied (true or false) -- Whether to allow players to fetch their car while it's occupied. If true, fetchinig a car will safely eject players from seating and flatbed modules if DismountPlayersOnFetch is true, else those players will be teleported with the car.
• CanDespawnWhileOccupied (true or false) -- Whether to allow players to use mycar destroy while their car is occupied. If true, despawning a car will safely eject players from seating and flatbed modules.
• DismountPlayersOnFetch (true or false) -- Whether to dismount all players from a car when it is fetched. Has no effect unless CanFetchWhileOccupied is also true.
• FuelAmount -- The amount of low grade fuel to add to the fuel tank when spawning. Only applies if the player has the spawnmodularcar.autofuel permission. When fixing the car or loading a preset, only the amount missing will be added to reach this minimum target value. Defaults to -1 which represents maximum stack size.
• FreshWaterAmount -- The amount of fresh water to add to each of the car's tanker modules when spawning. Only applies if the player has the spawnmodularcar.autofilltankers permission and has the AutoFillTankers setting on. Defaults to -1 which represents maximum stack size. Note: If for some reason the car has multiple tankers (i.e., no other modules), this amount will be added to each one.
• MaxPresetsPerPlayer -- The maximum number of module configuration presets each player is allowed to save.
• EnableEffects (true or false) -- Enable audio and visual effects when spawning a car from a preset, using mycar fix or mycar load.
• DisallowedMonuments -- List of monument short names where cars cannot be spawned or fetched. For example, ["powerplant", "trainyard"]. These do not have to be exact matches, so ["oilrig"] will apply to both "oilrig_1" and "oilrig_2". Requires the Monument Finder plugin to be installed. See the Monument Finder documentation for how to determine monument short names.
• Cooldowns -- Various cooldowns for balancing.

Server presets​

Server presets must be manually defined in the plugin's configuration file. A car can be spawned for a player using a server preset with the givecar <player> <preset> command. Cars spawned this way will use the settings that are provided in the preset, instead of using the general plugin configuration, player permissions and player settings. These cars do not count towards the player limit of one car, nor can they be spawned or interacted with using mycar.

Here is an example list of presets to get you started.
Here are all of the available options you can define per preset. The only required option is Modules. The rest default to 0 or false.

• Modules -- List of module item ids or short names that will be added to the car automatically. The number 0 represents an empty socket.
• Previously this field was named ModuleIDs. That name still works for backwards compatibility but it only accepts ids.
• CodeLock (true or false) -- Whether to deploy a code lock to the car.
• KeyLock (true or false) -- Whether to create a key lock and add a matching key to the player's inventory.
• EnginePartsTier (0 - 3) -- The quality of engine parts to automatically add to all engine modules (0 for no engine parts).
• FuelAmount -- The amount of fuel to put in the fuel tank (-1 for max).
• FreshWaterAmount -- The amount of fresh water to add to each tanker module if applicable (-1 for max).

Localization​

The default messages are in the SpawnModularCar file under the lang/en directory. To add support for another language, create a new language folder (e.g. de for German) if not already created, copy the default language file to the new folder and then customize the messages.

Developer API​

Cars spawned by the API methods are independent of mycar.

API_SpawnPreset​

• Spawns a car using the specified preset options, at the specified position and rotation.
• If the position is equal to Vector3.zero, the spawn position and rotation will be determined by the player.
• Returns null if the car could not be spawned, such as if the preset is missing module ids, or if another plugin blocked it with a hook.

Below is an example with all options provided:
The available options (e.g., locks, fuel, water) are the same as for server presets. See that section for more details.

API_SpawnNamedPreset​

• Spawns a car using the specified ServerPreset from the configuration file, at the specified position and rotation.
• If the position is equal to Vector3.zero, the spawn position and rotation will be determined by the player.
• Returns null if the car could not be spawned, such as if the preset does not exist.

API_SpawnPresetCar (legacy)​

Hooks​

CanSpawnModularCar​

• Called when a player or a plugin tries to spawn a modular car.
• Returning false will prevent the default behavior.
• Returning null will result in the default behavior.

CanSpawnMyCar​

• Called when a player tries to spawn their car with any of the various mycar commands.
• Returning false will prevent the default behavior.
• Returning null will result in the default behavior.

CanFetchMyCar​

• Called when a player tries to fetch their car with mycar fetch.
• Returning false will prevent the default behavior.
• Returning null will result in the default behavior.

CanFixMyCar​

• Called when a player tries to fix their car with mycar fix.
• Returning false will prevent the default behavior.
• Returning null will result in the default behavior.

CanLoadMyCarPreset​

• Called when a player tries to load a preset onto their existing car with any of the various mycar commands.
• Returning false will prevent the default behavior.
• Returning null will result in the default behavior.

CanDestroyMyCar​

• Called when a player tries to despawn their car with mycar destroy.
• Returning false will prevent the default behavior.
• Returning null will result in the default behavior.