The emplace command is a generic CLI tool used to take a value (or a collection of values) from a pipe and execute a code block for each one. It is primarily used to transform or act upon entities or sessions within a Toolshed context.
Usage Patterns
- Single Value: Takes one input from the pipe and executes the block once.
- Collection of Values: Takes an
IEnumerable<T> from the pipe and executes the block for every item in the collection. If errors occur during iteration, the process stops.
Available Local Variables
When using emplace, the command injects specific local variables into the block's scope based on the type of the piped input. These variables are read-only.
If the piped input is an EntityUid:
value: The current EntityUid.wx: The X coordinate of the entity's world position.wy: The Y coordinate of the entity's world position.proto: The ID of the entity's prototype (string).desc: The entity's description (string).name: The entity's name (string).paused: Whether the entity is paused (boolean).
If the piped input is an ICommonSession:
value: The current session object.ent: The EntityUid attached to the session.name: The session's name (string).userid: The session's NetUserId.
Note: The variable value is always available and represents the current item being processed.
# Example: Emplace a block over a list of entities (conceptual CLI syntax)
# entities | emplace {
# # Inside here, 'value' is the EntityUid
# # 'name' and 'wx' are available automatically
# print("Processing {name} at {wx}")
# }
