object.attach_to
This function attaches the context object to a given basis object. The context object will be moved to the basis object's position plus the supplied offset before the attachment is performed; an argument allows you to control whether the offset is relative to the rotation of the basis object. Note that the context object will not be rotated before the attachment is performed.
Attached objects effectively take on Phased physics; their movement cannot be impeded by other objects. Additionally, if objects are attached to a non-solid basis, such as a Flag Stand, then they themselves stop being solid; and if they are attached to an invisible basis, such as a Hill Marker, then they stop being visible altogether. Note that non-solid vehicles still offer entry prompts.
Arguments
- basis
The object to attach this one to.
- x
The X-coordinate to anchor this object at, relative to the position of the other object. Allowed values are integer constants between -128 and 127, inclusive, where 10 is equal to one Forge unit.
- y
The X-coordinate to anchor this object at, relative to the position of the other object. Allowed values are integer constants between -128 and 127, inclusive, where 10 is equal to one Forge unit.
- z
The X-coordinate to anchor this object at, relative to the position of the other object. Allowed values are integer constants between -128 and 127, inclusive, where 10 is equal to one Forge unit.
- reference_frame
Either the word relative, indicating that the position offset passed to this function is relative to the rotation of the basis object, or the word absolute, indicating that the position offset passed to this function uses the world axes.
Example
alias basis = global.object[0]
current_object.attach_to(basis, 0, 0, 20, relative)
Notes
Anchoring
Objects appear to be attached to the nearest node on a basis object's 3D model, with no apparent distance limit. For example, this piece of code would create a skull and anchor that skull to a Warthog's steering wheel:
alias some_warthog = ... -- global.object[0] = some_warthog.place_at_me(skull, none, none, 0, 0, 0, none) global.object[0].attach_to(some_warthog, 0, 0, 20, relative)
Even though the skull is attached to a point two full Forge units above the Warthog, it still attaches to the nearest node in the Warthog's 3D model, which happens to be the steering wheel. If a player enters the driver's seat and turns to the left or right, the skull will move and rotate in an arc above them, in synch with the steering wheel. Different offsets would anchor the skull to other nodes in the Warthog's 3D model, such as its tires.
Most objects have a node defined at their origins, and that can be used to avoid this behavior: spawn an extra object, have it copy the rotation of the basis, and then attach it to the basis with offset (0, 0, 0); then, attach the rest of your objects to that extra object.
Effects of attaching vehicles to other objects
Attaching a vehicle to an object will lock the vehicle in place. The pilot will be able to look around at any angle, but the vehicle will not turn, and the vehicle's weapons fire will be constrained to the weapon's turn radius.
Attached vehicles will not play any entry/exit animations (e.g. a Banshee's canopy opening and closing), but will instantaneously update to any animations' end states when detached (e.g. a Banshee's canopy will instantly snap open or closed as appropriate).
Bipeds in an attached vehicle will lose most animations. Passengers' hands may move slightly (and incorrectly) while reloading their weapon; though they have no reloading or weapon swap animations, appropriate sounds still play, and they cannot fire their weapons while the reload animation would be taking place. Some animations have player model jiggle physics; these jiggle physics remain functional even though the rest of the animation does not.
If a Banshee is performing an evasive maneuver at the moment it is attached, the maneuver will end instantly; no such maneuvers can be performed once the vehicle is attached.
Other notes
If either of the context or basis objects are no_object, or if both are the same object, then this function does nothing.
Armor Abilities equipped by players are an exception to normal attachment behaviors. If you detach an Armor Ability from a player's back, you can move it around or attach it without unequipping it from that player; however, the Armor Ability will automatically detach itself every frame. (Verified for Armor Abilities worn by Monitors, but not tested for Armor Abilities worn by Spartans and Elites.)
Attaching a biped to an object will lock the biped in place. If the biped is controlled by the player, they will be able to turn but not to move, and their first-person legs will desynch from their upper body.
When a biped enters a vehicle, it is considered attached to that vehicle. Scripts cannot attach it to something else while it is in the vehicle. Weapons being carried by a biped are expected to behave similarly.
If something is attached to a Monitor biped, it will bob up and down in synch with that biped's animation. All of a Monitor's nodes, including the one with the animation, are located at the same model-relative coordinate, and the one with the animation is the one that is found by the game engine when performing an attachment.
It appears that attaching an object to no_object and then detaching it will teleport it to the world origin. On Forge World, this is a point out by the canyon's beach.
-
If a player's biped is attached to an object that is destroyed on contact with a player, such as a landmine or powerup, then that player's camera will be locked to a consistent but unusual place; on Boneyard, this is a point in space far outside the map. Using Theater will show that the object appears to still exist, and that the affected player's biped is frozen in place inside of the object. The player's camera will remain fixed exactly in this spot even if they were in third-person view at the time they were affected.
In this state, the player can switch weapons, drop a detached turret if they are carrying one, fire their weapons, and throw grenades. All of these actions will occur relative to the player's "true" position at the object they were attached to, rather than at their camera position. Projectiles will fire roughly in the direction that the player is looking, but the yaw angle may be mismatched: it will be a combination of the direction that the player was looking just prior to the attachment, and the amount by which they have turned to the side after being attached, rather than matching their current camera yaw angle. The player will not be able to interact with objects near their "true" position; a vehicle next to them, for example, will not show button prompts for entry, and pressing the button to enter a vehicle anyway will not work.
The object to which the player was attached may activate some of its on-contact behaviors; landmines don't detonate, and Active Camo Powerups aren't destroyed and don't give the player camo, but the latter cause the player to constantly experience the sound loop that plays when camo is active.
These are the results of a local, single-player test. The networked behavior is not known.
-
If the player is attached to an Armor Ability, and if this would normally cause them to pick the Armor Ability up, then they will experience the same anomalies as if they were attached to a weapon that is destroyed on contact. They will not be able to use the Armor Ability during this time.
-
If the player is attached to a weapon right as they equip it (e.g. an unarmed player being attached to a weapon, such that they touch the weapon and equip it as they are attached), then they will equip the item normally rather than being attached to it... but they will also be launched with considerable force — possibly enough to break a map's boundaries.
If the player is attached to a grenade, and if this causes them to pick the grenade up, then the player will be unable to move, their animations will freeze, and their camera will be anchored to the spot the grenade used to be in.