Primary+Secondary Alignment

Last updated 2 days ago

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:

The <primary> direction defines the placement's +y direction.

The <secondary> 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.

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 <primary> and <secondary> 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 <primary> to up and the <secondary> to east (You'd use the 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:

The <primary> is set to south and the <secondary> 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.

The <primary> is set to the vector (0,1,1), i.e. the direction going "diagonally" up and south, and the <secondary> 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.

The <primary> is set to the vector (1,1,0), i.e. the direction going diagonally up and east, while the <secondary> 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 <primary> is set to the vector (-1,2,-1), i.e. a direction going up and northwest, while the <secondary> 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.

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:

Settings

Constant

Explicitly set a constant direction for all placements.

Syntax: Constant or Constant(Direction:<direction>)

Abbreviation: C or C(D:<direction>)

If you do not specify a <direction>, then:

the default direction is +y if you're setting the <primary>.
the default direction is +x if you're setting the <secondary>.

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 <secondary> 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 <primary> 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:<noise>)

Abbreviation: N or N(N:<noise>)

The default <noise> is Perlin(Freq:0.01).

Examples

//ezsc Clipboard Constant Noise

Top-down screenshot
<primary> is still up and only the <secondary> is set to Noise.
The default Noise is Perlin Noise.

//ezsc Clipboard Constant Noise(N:Vor(Freq:0.02,DistReturn:cell))

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 <primary> 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

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 <primary> 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.

//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

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.

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:<angle>)

Abbreviation: O or O(A:<angle>)

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 <angle> parameter:

//ezarray Clipboard Orthogonal Constant -n HORIZONTAL

Parameters

The following flags adjust how Alignments are calculated.

Snap to certain directions: `[-j <snapDirections>]`

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.

Last updated 2 days ago

Explanation

Overview