replaceme

The replaceme script command is used to create a new replacement entity for an entity. For item stacks, this command reduces the number of items in the stack by 1 and destroys the stack if the count reaches 0. Other entities are always destroyed. If the calling entity was destroyed then script execution ends after this command.

If the new entity's init scripts don't equip it or put it into an inventory then it will be put where the old entity was:

• The new entity will be placed at the same position as the old entity with the same rotation and same visibility.
• If the calling entity is an item contained in an inventory then the new entity will be inserted into the same inventory at the same position as the old entity if possible. The item will be combined into existing stacks in the inventory if possible which may result in the created item being destroyed again. If the item does not fit into the inventory or if it is not an item that can be put into inventories then it is dropped in front of the player instead.
• If the calling entity was equipped by the player then the replacement entity will be equipped in its place.
• If the calling entity was being dragged by the player then the new entity will be dragged.

If the calling entity is destroyed by this command then all its spells will be assigned the new entity as caster instead of ending.

To create a new entity without destroying the caller use spawn npc, spawn item, inventory add, inventory addmulti, inventory playeradd, inventory playeraddmulti or setweapon instead.

⚠️

This command has no effect while re-loading an area that was already visited before, e.g. in the reload event.

Usage

replaceme <script>

Context: Any Entity

Parameters:

Parameter	Type	Description
script	path	Script path (without file extension) of the entity to add, relative to a path depending on the entity type

Script path

The full script <path> depends on the type of the calling entity:

• graph/obj3d/interactive/npc/<script> for NPCs
• graph/obj3d/interactive/fix_inter/<script> for props
• graph/obj3d/interactive/items/<script> for all other entities

The type of the created entity depends on which of the following strings is contained in the the absolute script <path>. If the path contains multiple of these strings, the first matching type in the table is used. If it contains none then this command fails with no new entity being created and the caller not being destroyed.

String	Entity Type
items	Item
npc	NPC
fix	Prop
camera	Camera
marker	Marker

The entity class script is loaded from <path>.asl.

The initial mesh of the entity will be <path>.teo with the cooked mesh loaded from game/<path>.ftl. Either the raw mesh, cooked mesh or entity class script file must exist or the entity will not be created and the old entity will not be destroyed.

Items

If the filename component of the script path starts with gold_coin gold coin then the item will be treated as a gold coin which means that it will be added to the player's purse when the player interacts with it or when it would be added to the player inventory. Gold coins also somewhat act like stacks but use the price in place of the count and have the icon automatically selected based on the price.

If the script path contains the string movable then the item cannot be added to inventories and is dropped in front of the player instead whenever it would be.

The initial icon of the item will be <path>[icon] if it exists or graph/interface/misc/default[icon] otherwise. The icon size determines how many slots the item takes up in inventories except for movable items (which have no icon) and gold coins (where the icon depends on the price).

ℹ️  In version before Arx Libertatis 1.3 the icon file at the default path must also exist or the item will not be created, even for gold coins, movable items or items that change the icon in the load event.

Entity ID

The ID of the created entity can be retrieved via the ^last_spawned system variable. It will be made up of the filename component of the script path (the entity class) followed by _ and a previously unused four-digit instance number - meaning one that does not have an instance directory in the game resources under the script path and does not have an existing entity in the current area or save file.

This also means that it is not possible to create entities with instance scripts using this command (or any other script command).

If the created entity is destroyed before this command returns (because it was fully merged into an exiting stack or because the init events destroyed it) then then ^last_spawned will be none. If the init events spawn additional items then ^last_spawned will contain the ID of the last spawned item.

Entity initialization

The created item will be sent the load, init and initend events (in that order) before being placed where the calling entity was.