> For the complete documentation index, see [llms.txt](https://ezedits.gitbook.io/ezedits/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ezedits.gitbook.io/ezedits/commands/placement/primary+secondary-alignment.md). # Primary+Secondary Alignment The two alignment directions define the *orientation* at which the structure is placed. ## Explanation Every structure has an intrinsic "up" direction and an intrinsic "forward" direction. By default, structures are placed with their up direction facing, well, up (+y), and with their forward direction facing forward (+x). The most important thing is that now you can control how a structure is placed by defining where its up direction and where its forward direction should face. We let the user define the alignment using two directions: {% hint style="info" %} The `` direction *defines* the placement's +y direction. The `` direction *implies* the placement's +x direction. From all directions perpendicular to the primary direction, the chosen +x direction is the one that most closely aligns with the given secondary direction. Note: The primary and secondary may not be the same direction. {% endhint %}
More in-depth explanation using examples: Let's say this is our build that we want to place, by for example having it as our current WorldEdit clipboard. For reference, the red beam is facing towards positive x (east), the blue beam is facing towards positive z (south), and the green beam is facing towards positive y (up). We now want to place it at various orientations using any of the ezEdits structure commands. For this, we may define a `` and `` direction. Let us go through a few examples for a few such assignments of these parameters and try to understand what is happening: Let's set the `` to `up` and the `` to `east` (You'd use the [Constant](#constant) mode for that.) (These directions are the default directions): Our shape is pasted exactly in the same orientation as we copied it. Up is still up, right is still right, and so on. Now, consider the following three examples: 1. The **``** is set to **`south`** and the `` remains at `east`: Notice how, what was originally *"up"* when we copied it, i.e. the green beam in our case, is pointing into the direction that we set the primary to: *south*. Meanwhile what was originally *east*, is still *east*. The blue beam is going down as a consequence of this 90° rotation. 2. The **``** is set to the vector **`(0,1,1)`**, i.e. the direction going "diagonally" up and south, and the `` to `east`: Notice again, how what was originally *"up"* when we copied it, i.e. the green beam in our case, is pointing into the direction that we set the primary to: *diagonally up and south*. 3. The **``** is set to the vector **`(1,1,0)`**, i.e. the direction going diagonally up and **east**, while the `` is set to `east`: The green beam is correctly pointing along the primary direction, diagonally up and east. Whatever was pointing *up* when we //copy'd our clipboard is always aligned with whatever direction the primary is set to! But now, even though the secondary is set to *east*, the red beam is not pointing directly east anymore (but diagonally down and east). This is intended behaviour. Imagine if it were pointing east: Then the green and red beam would be at a 45° angle instead of the original 90° angle. Our structure would be deformed/bent/sheared. What we decided to implement instead, is that (while we align the structure's +y direction with the given primary direction) instead of aligning the structure's +x direction with the given secondary direction, we choose the direction that is most similar to the given secondary direction but that is still perpendicular to the primary. So, if the primary and secondary are not perfectly perpendicular, as in the example above, the secondary is swapped out with the most similar but still perpendicular vector! Just for reference, here's a small GIF that shows the remaining perpendicular secondary directions for a set primary direction: To give a final example: The **``** is set to the vector **`(-1,2,-1)`**, i.e. a direction going up and northwest, while the **``** is set to **`west`**: As you can see, the green beam, or what was originally up in our build when we copied it, is now pointing into our specified `northwest+2*up` direction, while the red beam, or what was originally east when we copied, is now pointing as `west` as it can while still being perpendicular to the primary. All of this applies independently of your current clipboard. Here's another structure at its original orientation followed by its placement aligned just like the previous example. ![](/files/3GL6Z4pyQ3uyACqM9kK8) ![](/files/mvRa9nJvY1ajp5hoKq1x) Can you see why setting the primary to `(-1,2-1)` and the secondary to `west` leads to the leaf being oriented like that? *** By the way, the command used was `//ezbrush place Clipboard Constant(Direction:(-1,2,-1)) Constant(Direction:west)` or, if you fancy abbreviations, `//ezbr pl Cl C(D:(-1,2,-1)) C(D:west)` With this primary + secondary system, we hope that you can easily and quickly construct your desired 3D orientation for each structure placement in any scenario.
*** ## Overview The primary and secondary can be set to either:
NameAbbreviationDescription
ConstantCExplicitly set a constant direction for all placements.#constant
RandomRRandom direction for each placement.#random
NoiseNDirection based on the evaluation of a noise function at the placement's position.#noise
AimAYour player aim direction.#aim
UpwardUThe most upwards perpendicular direction to your aim.#upward
PlayerRelativePThe direction from the placement's position towards the current player position.#playerrelative
SurfaceNormalSThe approximate surface-normal in the region of the placement's position.#surfacenormal
ViewDiffVDefine a direction using two clicks. Exclusively for brushes.#viewdiff
ExpressionEDefine a direction through an expression over each placement position.#expression
TangentialTThe direction tangential to the path. Exclusively for arrays.#tangential
OrthogonalOThe direction orthogonal to the path. Exclusively for arrays.#orthogonal
Mixed-Mix and combine any of the other Alignment modes using a weighted list.#mixed
*** ## Settings *** ### Constant Explicitly set a constant direction for all placements. Syntax: **`Constant`** or **`Constant(Direction:)`** Abbreviation: **`C`** or **`C(D:)`** If you do not specify a ``, then: * the default direction is **+y** if you're setting the ``. * the default direction is **+x** if you're setting the ``. There are various ways to define a direction. From using the axes, cardinal directions, vector notation, or player relative directions like forward, left, right, etc. Pro tip: You can also add directions together using simple arithmetic operators, like `east-z+(0,0.5,0)`. Pro tip²: Put `=` at the end to evaluate your direction expression as you are typing it.
Examples `//ezsc Clipboard C(D:(0,2,0)) C(D:east)` `//ezsc Clipboard C(D:(-1,2,-1)) C(D:east)` `//ezsc Clipboard C(D:(-1,2,-1)) C(D:-aim)`
*** ### Random Random direction for each placement. Syntax: **`Random`** Abbreviation: **`R`**
Examples `//ezsc Clipboard Constant Random` Only setting the `` to Random here, primary remains pointing up. Notice how our structure's up direction (green beam) remains up (primary is set to up), but each placement is randomly rotated around the primary (y-axis in this case) since the secondary is random. `//ezsc Clipboard Random Constant` Only setting the `` to Random, secondary remains pointing east. The terrain was replaced with glass so you can see better. Notice how the green beam is now facing all kinds of directions, but the red beam is roughly pointing east for all placements. `//ezsc Clipboard Random Random` If we set both to Random, then we get true random chaos.
*** ### Noise Direction based on the evaluation of a noise function at the placement's position. Syntax: **`Noise`** or **`Noise(Noise:)`** Abbreviation: **`N`** or **`N(N:)`** The default `` is `Perlin(Freq:0.01)`.
Examples `//ezsc Clipboard Constant Noise` * Top-down screenshot * `` is still up and only the `` is set to Noise. * The default Noise is Perlin Noise. `//ezsc Clipboard Constant Noise(N:Vor(Freq:0.02,DistReturn:cell))` * Same scenario as above but using [Cellular Noise](https://en.wikipedia.org/wiki/Voronoi_diagram#/media/File:Coloured_Voronoi_3D_slice.svg). * You can recognize how each cell has its own random direction.
*** ### Aim Your player's aim direction. Syntax: **`Aim`** Abbreviation: **`A`** Note: For brushes, `Constant(Direction:aim)` will use your player's aim direction at the time of brush binding, while `Aim` will use the player's aim direction during each brush act.
Examples `//ezsc Clipboard Aim Constant` If we set the `` to `Aim` then the up direction of our structure, the green beam in our example, will align with our current player's aim direction. My player model is included in the picture for reference. That's where I was looking when I executed the command. *The aim direction is visualized in F3+B with the thin blue line* ![](/files/1miOJc4IPnFm8nNMHo8Q) ![](/files/Efse0W8iTU93xYzZCQfT)
*** ### Upward The most upward perpendicular direction to your aim. Syntax: **`Upward`** Abbreviation: **`U`**
Diagram
*** ### PlayerRelative The direction from the placement's position towards the current player position. Syntax: **`PlayerRelative`** Abbreviation: **`P`**
Examples `//ezsc Clipboard PlayerRelative Constant` If you set the `` to `PlayerRelative`, then each structure is placed such that its up direction is pointing towards your player position. If you look closely, you can see my player model in the pictures. That's where I executed the command. ![](/files/qQc3itBl4oIVNaRKKrOu) ![](/files/Ip1ldIgDOvS50rpS6hxn) `//ezbr place Shape(S:Cone,P:diamond_block) PlayerRelative Constant -s 12,36,12`
*** ### SurfaceNormal The approximate surface-normal in the region of the placement's position. Syntax: **`SurfaceNormal`** Abbreviation: **`S`** By [normal](https://en.wikipedia.org/wiki/Normal_\(geometry\)) we mean the direction perpendicular to the terrain in question.
Examples `//ezbr place Shape(P:57,S:Cone) SurfaceNormal Constant -s 12,36,12` You can see our ingame alignment visualizer dynamically orient itself depending on which part of the terrain you are looking at when you are holding the brush.
*** ### ViewDiff Define a direction using two clicks. Exclusively for brushes. Syntax: **`ViewDiff`** Abbreviation: **`V`** Each placement requires a right click and a left click. The first right click sets the placement position at the targeted block. Left-clicking somewhere else then defines a direction: From your first (right) click target position to your second (left) click.
Examples `//ezbr place Clipboard SurfaceNormal ViewDiff` Here I set the primary to SurfaceNormal and control the secondary direction with a second click through the ViewDiff mode. Pay attention to my hand. You can see me alternating between right- and left-clicks. A right click sets the placement position, and a left click sets the ViewDiff direction. Our ingame alignment visualizer dynamically updates depending on your movement and your actions. `//ezbr place Shape(S:Torus(Thickness:0.4),P:57) PlayerRelative ViewDiff -s 20,20,30 -k x -c 90` This torus shape required a few more parameters, so this example turned out a bit longer than usual. What's important to notice though is that the primary is set to PlayerRelative, meaning the top of the torus always faces the player, and the secondary is set to ViewDiff, meaning the final orientation is determined with a second click. Here, after each right-click, I alternate between left-clicking above and left/right from the placement position to create a linked chain.
*** ### Expression Define a direction through an expression over each placement position. Syntax: **`Expression(Expression:=,Space:)`** Abbreviation: **`E(E:=,S:)`** Mandatory Arguments: * **`Expression`** **(****`E`****)**: An expression defining a 3D vector for each position in space. * Input variables are `x`, `y`, `z`. * Output variables are `rx`, `ry`, `rz`. * For each placement, the expression will evaluated with the according placement position and the result used for the placement's alignment. Optional Arguments: * **`Space`**** (****`S`****)**: Defines the domain of the input variables. * Defaults to `WORLD`. * `WORLD`: the placement position. x, y, z, are in world coordinates * `LOCAL`: When used in... * ezplace: Always 0,0,0. * ezscatter: Coordinates shifted such that the center of the region is 0,0,0. * ezarray: x=y=0. z=0 at the start of the path, z=L at the end of the path, whereby L is the length of the path. * `NORMALIZED`: When used in... * ezplace: Always 0,0,0. * ezscatter: Coordinates normalized to the region such that x,y,z ∈ \[-1,1]. * ezarray: x=y=0. z=0 at the start of the path, z=1 at the end of the path.
Examples `//ezsc TS(P:##Grayscale,S:Fur,T:=y) C Ex(E:"=rx=z;rz=-x",S:N)` * `TS(P:##Grayscale,S:Fur,T:=y)` is a fur shape in a grayscale gradient. * `C`, the primary, using the default up direction. * `Ex(E:"=rx=z;rz=-x",S:N)` sets the secondary to (z,0,-x), whereby x,z are the normalized placement position coordinates. `//ezar Sh(S:Fur,P:clay) C E(E:"=rx=sin(2*pi*z);rz=cos(2*pi*z)",S:N) -g -12` This example shows how the z coordinate ranges from 0 to 1 along the path when using normalized mode.
*** ### Tangential The direction tangential to the path. Exclusively for arrays. Syntax: **`Tangential`** Abbreviation: **`T`**
Examples `//ezarray Clipboard Tangential Constant -g 11 -o 2` The *Tangential* direction points tangential to the spline path at the position of the placement. If you set the primary to *Tangential*, the top of the shape is pointing along the spline like this.
*** ### Orthogonal The direction orthogonal to the path. Exclusively for arrays. Syntax: **`Orthogonal`** or **`Orthogonal(Angle:)`** Abbreviation: **`O`** or **`O(A:)`** The angle, given in degrees, defines the initial direction of the orthogonal direction, whereby 0° and 360°, will face up, 90° and 270° face left and right, and 180° faces down (at the first part of the spline at least. It may twist further along if the normal mode is set to CONSISTENT, which is the default setting).
Examples `//ezarray Clipboard Orthogonal Constant` The *Orthogonal* direction points perpendicular to the spline path at the position of the placement. If you set the primary to *Orthogonal*, the top of the shape will point perpendicular to the spline path like this. Here's a GIF going through the `` parameter: `//ezarray Clipboard Orthogonal Constant -n HORIZONTAL` The [-n flag](/ezedits/commands/placement/array-parameters.md#spline-orientation-n) has a direct influence on the orthogonal direction.
*** ### Mixed You may combine any number of any of the other Alignment modes using a weighted list: Syntax: `%,%,...` Alignment directions are scaled by the given weight and summed up together.
Examples ` //ezsc Sh(P:clay,S:Cone)`` `` `**`Constant`**` `` ``-s 11,30,11 -n 1 ` (for reference) ` //ezsc Sh(P:clay,S:Cone)`` `` `**`10%C,10%R`**` `` ``-s 11,30,11 -n 1 ` GIF going through * `10%Constant` * `10%Constant,1%Random` * `10%Constant,2%Random` * ... * `10%Constant,10%Random`
*** ## Parameters The following flags adjust how Alignments are calculated. *** ### Snap to certain directions: `[-j ]` This parameter allows you to restrict the chosen alignment direction to the specified subset. E.g. snapping to / only allowing cardinal direction, i.e. 90° rotations. Available options: * **`MULTIPLES_90`** * Only allows multiples of 90°, i.e. all axis-aligned directions. * **`MULTIPLES_45`** * Only allows multiples of 45°, i.e. axis-aligned directions AND all perfect diagonals. * **`MULTIPLES_22_5`** * Only allows multiples of 22.5°. * **`MULTIPLES_15`** * Only allows multiples of 15°. * **`DIAGONALS_1_1`** * Only allows axis-aligned directions, and perfect "1:1" diagonals. * **`DIAGONALS_2_1`** * Only allows the `DIAGONALS_1_1` directions and any "2:1" diagonals. * **`DIAGONALS_3_1`** * Only allows the `DIAGONALS_2_1` directions and any "3:1" diagonals. * **`DIAGONALS_4_1`** * Only allows the `DIAGONALS_3_1` directions and any "4:1" diagonals. * **`DIAGONALS_5_1`** * Only allows the `DIAGONALS_4_1` directions and any "5:1" diagonals.
Examples `//ezbrush Cl Constant ViewDiff -j MULTIPLES_45`
*** ### Perturb Secondary: \[-x] In our primary+secondary system, placement fails if both vectors are collinear (which simply means they are on the same line). By enabling this flag ezEdits tries to circumvent that case by perturbing the secondary direction by a small amount. ***