Page modified from the in-complete Forge Wiki[1] Edit

Basic Attachment Concepts Edit

Starcraft II actors are various game entities that deal with all non-gameplay affecting things (visuals, sounds, attachments, and many more). These actors are asynchronous; that is, they render separately for each player (as opposed to critical gameplay aspects of units, like health, which must be synchronized over

@attach signals Starcraft II to create and attach an actor to another actor at an attachment point (these points are built into the model itself. If the model lacks any points, the attachment defaults to the Origin position of the actor being attached to).

In the context of Cortex, we mostly care for the visual aspects of attaching actors. The basic original @attach command is simply the following:

@attach [Actor] [Point]

where [ _ ] defines a user-inputted parameter.

Advanced Attachments (@attach+) Edit

This guide covers the basic usages of @attach+, the advanced version of the @attach command that has been implemented in Forge. This command will be kept separate from the basic @attach command simply because of significant differences in usage. @attach+ also performs slightly differently in terms of the actor that is attached.

The full syntax of @attach+ is the following:

@attach+ {-m} [ Actor/Model name ] [ Point{_INDEX} ] {[offX] [offY] [offZ]} {{-r} [rotX] [rotY] [rotZ]} {[SOp1] [SOp2] [SOp3]...}
  • [ _ ] defines a user-inputted parameter
  • {-m} and {-r} are optional flags that are inputted as is
  • { } surround input parameters that are optional or can be skipped

Because almost all the parameters are optional, this command has various different ways of usage. The rest of this page will go through most of the possible combinations of the parameters.


{-m} flag : Edit

The '-m' flag will cause a "Model" type actor to be attached, rather than a normal actor. The "Model" type actor behaves differently than normal actors. The model will be static, it will remain a constant size, and cannot be affected by other Cortex commands.

An example of attaching a model:

@attach+ -m zealot weapon

This would attach a "zealot" model to the weapon attachment point of the actor this command is used on.

Note: because you are attaching a "Model," you must input a model, not an actor (that is, a model one would use with the @modelswap command).

There may be work in the future to make these Model actors affected by Cortex commands. (e.g. Wyvern has this capability with its actor-directed @actormessage command.)


[ Point{_INDEX} ] : Edit

Most attach points on models have an index associated with it (e.g. Hardpoint07 or Target07). The basic @attach has been unable to properly attach to an index. @attach+ can. Suppose you want to attach a marine to Hardpoint04 on a unit; you can select the unit and use:

@attach+ marine hardpoint_4

Supplying an index is optional; simply inputting:

@attach+ marine hardpoint

will attach the marine actor to the default Hardpoint on the unit @attach+ is being used on (assuming it exists).

Note: attachment points with an index work the same as a default point; if it does not exist on the actor being attached to, the attachment will default to Origin.


X,Y,Z offset : Edit

With @attach+ you can optionally specify an absolute 3-D offset (in **absolute** X,Y,Z coordinates in the Starcraft II map, where X,Y are planar coordinates and Z is the height coordinate) from the attachment point: The order for an offset specified is [ X ] [ Y ] [ Z ]. Such as the following:

@attach+ marine hardpoint 2 3 1

Assuming Hardpoint exists on the actor being attached to, the marine will be attached with an offset (x,y,z) = (2,3,1) from this point.

You do not have to enter all the coordinates (unless you are proceeding to also specify rotations and/or site operations). The following both work:

@attach+ marine hardpoint 2

Results in a (x,y,z) = (2,0,0) offset.

@attach+ marine hardpoint 2 3

Results in a (x,y,z) = (2,3,0) offset.


Rotations : Edit

The -r flag specifies a rotation (to distinguish these three coordinates from an offset). A rotation requires three coordinates such as the following:

@attach+ marine hardpoint -r 1 1 2

These three coordinates actually specify a rotation vector, not an absolute position. Because this is a vector, the numbers are all relative to each other, and the effective vector is simply normalized to 1. So in the example above, the three values are equivalent to .5 .5 1 and 5 5 10. Any scalar multiple of (1,1,2) will be equivalent.

As an advanced note, there are actually 6 rotation parameters, although @attach+ only has 3 supported. These 6 parameters likely refer to Euler Angles.

Rotations can be combined with offsets like the following:

@attach+ marine hardpoint 2 1 2 -r 1 1 2

This will attach a marine to the hardpoint with a (2,1,2) offset and a (1,1,2) rotation.


Site operations : Edit

Site operations are themselves a special class of actors that affect how other actors are attached. These are generally prefixed by SOp. Some useful basic site operations include a 90 and 180 degree rotation, SOp90 and SOp180. One can apply this 90 degree rotation site op on an actor's attachment point with the following:

@attach+ marine hardpoint SOp90

This will attach a marine to the hardpoint with a 90 degree rotation.

Site ops can be combined with rotations or offsets, such as the following:

@attach+ marine hardpoint 2 2 1 SOp90
@attach+ marine hardpoint -r 2 2 3 SOp90
@attach+ marine hardpoint 2 2 1 -r 2 2 3 SOp90

Site operations are always specified at the end of @attach+. You can also apply as many site operations as you want, by separating each site operation with a space:

@attach+ marine hardpoint 2 2 1 SOp90 SOp180 SOp90 SOp90

In theory this should result in a marine attached to the hardpoint with a (2,2,1) XYZ offset and a net 90 degree rotation. However, site operations do not always apply well in the engine. Multiple site operations often do not work well and do not have their intended effect. This can only be figured out by testing.

There are many different site operations that one can find by doing search actor SOp ingame (or equivalently searching the actors in the Catalog UI panel in the Forge toolbar).