04. Primitives
About Primitives
VSAR provides a set of procedural primitives. Procedural primitives, as opposed to static elements, are customizable and can be modified at runtime, which can be useful for dynamic geometries such as bar charts, pie charts and so on.
List of Primitives
Cone
A beveled cone. Top vertex can be beveled as well. It is a component of the arrow.
Cylinder
This is the base for Pie charts. Many configurations are possible, including cylinders with holes.
Arrow
An beveled Arrow composed of a Cone and a Parametric Curve 2D (parabola).
Moebius Strip
Möbius loop is a surface that can be formed by attaching the ends of a strip of paper together with a half-twist.
Box
A simple beveled box.
Torus
A Torus.
Sphere
An ellipsoid displayed with triangles (aka icosphere).
Disk
A flat, simple disk.
Text
Text is considered deprecated please use Camio 2D/3D Text Component or Text3D
📝 Alternative is provided by Unreal Engine called “Text3D” (it is considered experimental), it is component that can be added to actors.
📝 if text transition is needed, refer to Camio 2D/3D Text Component section for text with transition out of the box.
Usage
A primitive is represented by a Component object in the Unreal Editor. Multiple Components can be attached to an Actor object (e.g., a pie chart would be composed of multiple MtCylinder components). The Component inherits the parent Actor’s transformation in addition to its own transformation (Location, Rotation, Scale).
Each primitive exposes a set of properties that the user can get/set in real time with the Editor UI or Lua scripts.
The property center location is common to all primitives and defines the normalized coordinates of the primitive’s anchor point in 3D space.
For example, a “bottom-center location” anchor point for a box would be equal to a value of (0,0,-0.5).
Unreal Editor
Tip: the user can search for the Component in the search bar (e.g., MtBox, MtCylinder, etc.).
Edit the properties in the Details Panel.
Lua Scripting
For documentation about LUA commands, please refer to PRIME VSAR API Guide
Transitions
⚠️ This feature is still in Beta, testing was not finished !
All primitive components (except MtTextPrimitive) support show/hide transitions. Users can choose from multiple types of transitions, directions and customize Transition Duration time. Transitions can be started from the details panel (by buttons), or call them from blueprints.
Color, Metallic, Specular, Roughness, Emissive Color are material parameters. Can be set by users.
Transition types
Push Wipe Fade Radial Fade Radial Wipe
Primitive Actor
MtPrimitiveActor supports transitions. There are Show and Hide buttons in details panel, which execute show or hide transition on all its components (in case, the component supports primitive transitions)
When creating a new blueprint actor in blueprint editor, go to Class Settings and in the details menu, select Parent Class as MtPrimitiveActor. This enables usage of Shoiw/Hide buttons from details and usage of actor functions in blueprints.
Blueprints
PlayShow - starts show transition
PlayHide - starts hide transition
PlayNext - starts transition according to current state, if object is shown, hide will be played, if object is hidden, show will be played. When next is called upon the actor, each component decides for itself, which transition will be played. (so if one component is hidden and second is shown, they will both play show/hide accordingly)
TakeShow, TakeHide, TakeNext - performs show/hide/next transition. This is latent action, so blueprint execution will be paused until transition finished. With an actor, execution is paused until all components have finished transitioning.
Advanced
In the advanced panel, users can change Alpha parameters. Alpha determines the stage of transition. Its values are in range 0-1, 0 for hidden and 1 for shown. Beware, that playing transition changes this parameter.
Custom Float Curve
User can specify own Custom Float Curve, changing speed of the transition. This curve should map 0-1 (time from start to finish - 0 is start and 1 is finished) to 0-1 (Alpha values - transition stage). That means, it should cross points [0,0] and [1,1]. For Show, left to right pass is made, for hide the direction is opposite (right to left).
Default Float Curve (when Custom Float Curve is not set - or set to None)
Custom float curve.
With this curve transition is visibly slower around hidden objects. Using custom curves with customizing transition duration gives users a lot of options for controlling transition speed.
Material Editing
Users can even edit material. For that, the user should copy the material asset M_PrimitivesMaterialMaskedWithTransitions.
In the Content Browser in the right corner, in settings, check Show Engine Content and Show Plugin Content.
Material can be found in All -> Engine -> Plugins -> PRIME VSAR Content -> Primitives -> Materials. User should not under any circumstances edit this material (it will change it in Engine globally) directly, Please Right-click and Duplicate it.
It is recommended to name duplicated material properly, so it would not be mistaken for the original material.
User can then do any changes on the copied material, then create material instance (Right-click edited material and Create Material Instance)
and then select it (the instance) as Masked Material in details. (drag and drop)
In order for transitions to work, users should not edit anything changing the opacity mask and world position offset. Adding textures or other material properties should be fine.