ShipSort - Item sorting mod for Lethal Company

Documentation for users

Basic usage

After installing the mod, simply type /sort in the game chat.

This should sort all scrap on your ship onto the wall and put all your tools into the cupboard (or on the floor, if the cupboard is stored)

Some tools are automatically put on the cruiser (if you have one).

For maximum consistency you can only use /sort while your ship is in orbit.

Advanced usage (alternative/custom scripts)

This mod is highly customizable by using lua scripts to create item arrangements.

The default arrangement described above is produced by the bundled sort.lua script, however it can be easily adjusted by changing the ScriptPath config value.

An alternative script is bundled with the mod: sort_sm.lua - a reimplementation of the ScrapMagic sorting feature

The bundled scripts contains some options that can be easily adjusted near the top of the file. Make sure to rename the file if you do this, as otherwise your changes may be lost on updates.

While scripts run in an isolated environment, there is always a risk when running arbitrary code. Only use scripts from trusted sources

The path is interpreted relative to the BepInEx/config directory in your profile or as an absolute path.

Other config values

• General/Timeout: To prevent freezes caused by bad scripts, a maximum execution time limit is set. If this expires, the script execution will be aborted and no items will be sorted.
• General/AutoSort: When you're hosting a lobby, the mod will automatically sort all items when
  • a save is loaded
  • the ship leaves orbit
  • the ship returns to orbit
• Networking/ShareConfig: The script you selected will be shared with any clients also using the mod in your lobby. This results in less config conflicts.
• Networking/UseSharedConfig: If you joined a lobby where the host has shared their script, this can be used to force your own script instead.
• Networking/SharedConfigSizeLimit: Prevents any abnormally large scripts sent by the host from being decompressed.

Command arguments

_{Command arguments are anything you type after the command: /command argument1 argument2 ...}

Any arguments you pass to the /sort command are passed to the script.

Common errors

• Script '...' could not be found: The script file referenced in the config is not available. Make sure the path is valid.
• Script execution timed out: The script took too long to execute, increase the General/Timeout config value if this happens too often.
• Version conflict (...): The script was created for a different version of the mod, things may break. If it works fine, you can remove the expect_version(...) instruction in the script to remove the warning.
• ... items couldn't be sorted: Some positions were invalid, contact the script creator about this and make sure to provide all error messages found in the game logs.
• Script error: ...: The script failed to execute, contact the script creator about this and make sure to provide the full error message found in the game logs.
• Script compilation error: ...: The script file contains an error, contact the script creator about this and make sure to provide the full error message found in the game logs.
• Script result invalid: ...: The script exited abnormally, contact the script creator about this and make sure to provide the full error message found in the game logs.

Sub-commands

The following sub-commands are available:

• /sort-reload - Reloads your selected script from disk
• /sort-status - Displays some information about the mod (such as the current script and information about the previous sort)

Documentation for script developers

_{When developing scripts, it is recommended to use a debug build of the runtime, as it provides useful tools, warnings and log messages for script development. See below for more information}

Concept

A sorting script receives a table of items and returns a table of positions, both using arbitrary indexes for item identification.

The script should use its code to generate those item positions.

Return values

The script should return a table containing ItemPos or Vector3 objects at the indices of their respective items.

If an item has no assigned position (nil), the item will not be moved.

Lua environment

This mod uses Lua-CSharp (v0.5.6 for Lua 5.2) to run scripts, see its compatibility section for more information.

Only the basic, string, table, math and bitwise libraries are loaded.

The loadfile and dofile functions are removed.

Globals

• items (table): A list of item definitions
• moon (table): A table containing information about the current moon (see moon definition)
• remaining_days (int): The amount of days remaining in the current quota
• unlockables (table): A table of booleans representing different unlockables on the ship and their availability (use the Unlockables enum to index this)
• args (table): A list containing the user-provided command arguments
• about (string): A short description of the current runtime (baer1.ShipSort vX.X.X)
• script (string): The file name of the current script (not the full path)
• version_major (int): The major version of the runtime
• version_minor (int): The minor version of the runtime
• version_patch (int): The patch version of the runtime

Item definitions

Each item definition is a table with the following values:

• name (string): The item object name, without the (Clone) added by Unity (Shovel: ShovelItem, Bottles: BinFullOfBottles, see below)
• type (string): The item script type (Zap Gun: PatcherTool, Generic scrap: PhysicsProp, etc.)
• scrap (bool): Whether the item is scrap (not a tool)
• large (bool): Whether the item is two-handed
• arg (object): Misc. value related to the item (amount of shells in a shotgun, whether a radar booster is enabled, see SortAPI.ItemArg for more details)
• index (int): 1-based index of the item based on name
• count (int): total amount of items with matching name

Vanilla Items

Last updated for v81

Moon definitions

A moon definition is a table with the following values:

• id (int): The internal moon id (SelectableLevel.levelID, see below)
• name (string): The moon name
• scene (string): The moon terrain scene

Vanilla Moons

Last updated for v81

Enums

Some enums are made available as global constants (Enum.Value would become ENUM_VALUE)

Unlockables

Parent objects

Relative objects

Rotation modes

Transform objects

Types/Classes

Vector3

Each Vector3 contains x, y and z values. You can create one using Vector3(float x, float y, float z)

The following operations are supported:

• Vector3:x
• Vector3:y
• Vector3:z
• Vector3:Equals(Vector3)
• Vector3:normalized()
• Vector3 + Vector3
• Vector3 - Vector3
• Vector3 * float
• Vector3 / float
• -Vector3
• Vector3[0-2] (zero-indexed)

Some commonly used values have constant representations:

ItemPos

An ItemPos object represents instructions on how to position a certain item, such as a position and rotation.

It is made up of the following fields:

• position (Vector3): The coordinates where to put the item
• parent_to (PARENT) [DEFAULT: PARENT_SHIP]: The transform to which to parent the item
• relative_to (RELATIVE) [DEFAULT: RELATIVE_PARENT]: The transform relative to which the position is calculated
• rotation (int) [DEFAULT: 0]: The rotation of the item around the Y axis (always limited to 0-360)
• rotation_mode (ROTATE) [DEFAULT: ROTATE_LOCAL]: How to adjust the rotation angle

An ItemPos is created using ItemPos(Vector3 position) and additional fields can be set using :with_field(value):

ItemPos(VECTOR3_ZERO):with_rotation(90):with_rotation_mode(ROTATE_WORLD)

RaycastPos

A RaycastPos object represents instructions on how to perform a raycast.

It is made up of the following fields:

• position (Vector3): The raycast origin
• direction (Vector3): The direction to cast the raycast in
• relative_to (TRANSFORM): The transform relative to which the position and direction are calculated

While a RaycastPos can be created manually using RaycastPos(Vector3 position, Vector3 direction, int relative_to), unless you are using all three options you should just use the raycast function directly.

Utility functions

Print

void print(...)

The print function outputs the provided arguments to the game log (separated by spaces)

Error

void error(...)

The error function outputs the provided arguments to the chat (separated by spaces) and aborts further script execution

Expect version

void expect_version(int major) void expect_version(int major, int min_minor)

The expect_version function verifies if the script is compatible with the runtime version and informs the user about any incompatibilities.

The runtime should follow semantic versioning, where the major version should match and the minor version should match or be greater.

This function can only be used once

Raycast

Vector3? raycast(RaycastPos raycast_pos) Vector3? raycast(Vector3 origin) Vector3? raycast(Vector3 origin, Vector3 direction) Vector3? raycast(Vector3 origin, TRANSFORM relative_to) (TRANSFORM enum)

The raycast function performs a raycast immediately, which collides with the same layers as an object being dropped.

In cases of missing arguments, the following defaults are used:

• direction: VECTOR3_DOWN
• relative_to: TRANSFORM_SHIP

Repeated calls may be expensive, some sort of caching is recommended.

Transform

Vector3? transform(Vector3 point, TRANSFORM from, TRANSFORM to) (TRANSFORM enum)

The transform function transforms a point from from-space to to-space immediately.

Debug build

The release build of this mod is stripped of the script development helper tools.

Therefore, when developing a script, consider using a debug build of the mod.

Debug tools include, but are not limited to:

• Sort helper: displays the coordinates where you dropped an item (see /sorthelper)
• Execute from disk: executes the script straight from disk, instead of the cache (no need to reload your script after every change)
• Verbose logging: Prints every resulting item position in the log

_{Some features mentioned above only activate in a singleplayer LAN lobby}

You can obtain a debug build from the latest GitHub release (release-debug.zip).