Skip to content

Component Guidelines

Simumatik offers advanced tools to create custom components. This flexibility is a strength, but as with all engineering tasks, complexity needs to be managed. The Simumatik team has put together a set of guidelines to promote best practices when creating components and building systems. These guidelines are based on knowledge gained when working with industrial clients on commercial projects. Following these guidelines will promote consistency and clarity, making components easier to use, and increase reusability of your components.

Component Classification

In simumatik anything can be considered a component: a product, sensor, motor, robot or even a plc. The following classification may help to identify components that share some properties or functionalities and require some specific considerations. Once classified, we recommend to follow the guidelines and recommendations in the corresponding tutorial before starting to create the component (next chapter). We also recommend to base the new component on a similar one and modify the necessary attributes instead of creating it from scratch. The suggested classification is the following:

A - Decorative components:

Components with no physics, behavior or ports. They can be modelled using just one or several visuals. Consider using as simple as possible 3D assets given that they do not provide any functionality to the model (i.e. Simumatik logo). See Tutorial 1 and chapters visuals and GLB Model Simplification.

alt text

B - Basic components without physics:

Components that do not require physics but may have some functionality which requires some behavior logic and even ports to interact with other components. They do not interact with other components using the physics engine, so just one link with no mass is used. One or several visuals can be used to animate the component and the “user_action” may be useful to allow user interaction. (i.e. a Button, Motor contactor, Fuse,…) See Tutorial 2 and chapters Interfaces, visuals, User action, GLB Model Simplification.

C - Basic components with physics:

Components that just have a unique link (base_link) and use physics to model the collision shape or dynamics. This group includes components that represent mechanical parts that interact with other components through the collision shape and may or not be dynamic, i.e. conveyors, ramps, buffers, magazines. It also includes components that represent products and are always dynamic, i.e. boxes, pallets. It is important to consider the importance of attributes such mass, friction and bounciness to get the desired dynamic results. The collision surface is a feature that can easily replicate conveyor behavior. In addition, it is important to pay attention to the collision shapes in order to reduce computational cost. See Tutorial 3 and chapters Geometry and Appearance, Physics.

D - Sensoric components:

Components which include specific features to interact with the physics engine and detect components within a range. This group includes simple components such inductive or photoelectric sensors, but can also include RFID devices, cameras, etc. They require understanding how the physics engine handles collision filtering using the collision_tag variable. Usually, these components can be modelled without collision shapes. Several visuals can be used to display sensor status. See Tutorial 4 the chapter on Physics.

E - Mechatronics components:

Components including one or several movable parts. They are modelled using several links and joints. See Tutorial 5-

alt text

Smart components

Elements with external communication using drivers (i.e. PLC, IO modules, smart sensors and actuators)

Component Creation

In order to create a component, it is necessary to consider four different aspects that the simumatik data-model provides: Interfaces, Geometry and appearance, physics and behavior. On top of that, the metadata


The metadata is used to describe a component and to search for it. It is important to fill the metadata to allow other users to use and understand the component.

The following are the attributes that needs to be filled:


The name should be a short free text to identify the component. It should be as short and descriptive as possible, like a label. Avoid introducing manufacturer or model details here and use the metadata attributes for that. I.e. “Analog Input Card 8 ports”, “Push Button with light NC”, “3 phase motor”.


Thumbnails are used in the component browser to give a quick overlook. Thumbnails are created in the component editor by pressing the camera button in the 3D editor. The whole component should be visible with eventual defining features visible, such as ports, knobs or other parts of the model important to the components functionality.

alt text

alt text


This attribute is used for indexing the component for the search function. Several words can be added and multiple keywords give a higher chance of being found in a search. Keep the search words consistent, relevant, and add just key features and component attributes. I.e “pushbutton, push button, light, normally open, NO”. Avoid using unnecessary keywords as this may have the component appearing in irrelevant searches, for example too generic or normative words ("component", "fast", "good").


This field is mandatory if it is a commercial component. Make sure to use the official manufacturer name and check if it exists before setting it. This attribute will allow narrow filtering of components.


This field is mandatory if it is a commercial component. Make sure to use the official manufacturer model.


This field is recommended for all components. If not sure which is the complete classification (8 digits), it is better to set a higher level of classification (6 or less digits). This attribute will allow narrow filtering of components.


It is used to document the component, explain its functionality, main features, ports and public variables. The goal of the description is to explain to the user how to use it and what to expect from it. Example:

“Analog card with 8 outputs ports and configurable output voltage. They must be connected to a PLC Rack to work.


– x1: Electric input 24V

– x2: Electric input 0V


– voltage_range: Output voltage range used by the card in volts”

alt text


Interfaces describe how the component can be connected to other components or 3rd party software and hardware.


A picture should be used as a symbol if the component has any port. For commercial components it is recommended to search for the original symbol provided by the manufacturer. When original symbol is not available a generic symbol can be used.

The symbol allows using PNG or SGV asset files, but if possible use SVG images that will scale better. The size of the symbol has to be adjusted so it has the right proportions.

alt text


Port names should be set according to the symbol. Follow ISO standards or look at a similar commercial component if the created component is non-commercial (or dummy). Make sure that the port’s position (2D) and origin (3D) are correctly set to match the symbol and the geometry of the component.


The inputs (red cones) should point into the model, and the outputs should point out of it

Communication drivers

Drivers are used to communicating through the gateway. Make sure to connect driver variables from/to the behavior to handle the connection and variable update.


In the future it should be avoided making driver variables public because they will be available in the workspace anyway.

Geometry and Appearance

The geometry represents the visual appearance of the component. The coordinate system used in Simumatik is Z up, which means the X-Y plane represents the floor. We recommend building components considering this, so components that usually are placed on the floor, such conveyors or robots, are standing on the Z axis. For other components, as general equipment introduced inside cabinets, sensors or actuators, the recommendation is that they should be facing the X axis and standing on the Z axis. In addition, for components that are dynamic, the recommendation is that the origin matches their center of mass. For static components it is also valid to position them so they are positioned over the floor plane (Z=0).

It is important to consider that the complexity of the geometry will have a direct impact on the computer performance. Most of the computers won’t have issues to compute the server side but may struggle with the 3D rendering if no dedicated graphic card is available. The detail level must strike a balance between quality and usability.


It is possible to use basic geometrical figures such as box, cylinder, sphere, etc or an asset (GLB file) to represent the visual geometry. One link can have more than one visual.

For components of class A, B or D, which do not require physics it is recommended to use several visuals and use their attributes to animate them (move, rotate, change color, etc…)


In case of using basic geometries the color or texture of the visual can be changed with this element. Texture files should be PNG format. Try to avoid using complex textures that may have a negative impact on the performance.

User action

User action is a variable that allows detecting when a user has clicked on a visual. The variable will be true while the mouse is pressed and can be connected to a behavior to animate or change the behavior of the component.

GLB Model Simplification

Here are some recommendations that can be followed to create optimized GLB assets using Blender:

  • Simplify the model to only include the necessary parts (remove screws, nuts etc.).
  • Make sure that there is only one node in the .glb file. Several nodes can be combined in one.
  • Apply the decimate modifier in Blender to reduce triangle count.
  • Use the gltfpack tool to further optimize the model.
  • Open the model in the online glTF Viewer to check it’s consistency.

alt text


Simumatik uses a physics engine so it is possible to describe the collision shapes and dynamics of the components. In addition, the engine allows some extra features such as raycasting (useful to model sensors) or force application (blow effect). It is very important to remember that components can be static (mass=0) or dynamic (mass>0). Static components won’t move even if they detect a collision.


Use default values and modify the mass when necessary. The mass value should be between 0.05 and 1. Try to avoid big mass differences (x2-3) between connected links and even consider the components with which it will interact.

Components can have one or more links, allowing to build multibody components which should be connected using joints, such as robots. Unlike other platforms, Simumatik allows connecting links forming a loop. Tru to reduce the amount of links as much as possible, for example, adding more than one degree of freedom to a joint.


Explain when to use joints vs visuals (TODO)

  • Axis: Fixed joints and several degrees of freedom
  • Limits: Effort and velocity
  • Joint_motor: (TODO)
  • Joint_sensor: (TODO)

Collisions Shape

Collisions are handled with collision shapes that are separate from the 3D-model. As with the 3D-mesh, the collision shape should be kept as simple as possible for performance reasons. It is possible to use the 3D-mesh as a collision model, but it is preferred to use specific shapes.

  • Try to approximate the collision with one or several basic geometries found in Simumatik

  • If the shape can be approximated with a convex shape, use the simplest GLB as possible and activate the as_convex_hull flag.

  • Another approach is to use a GLB that is split in parts that are already optimized (basic geometries or simple convex shapes)

  • Finally, the most expensive is to use any glb and activate as_triangle_mesh (but works just for static objects). Be careful with shapes with a big amount of triangles.

alt text


It is possible to use the physics engine to create raycasts and detect nearby components to model sensors. It is recommended to reduce the amount of rays as much as possible and define the collision_tag as specific as possible to narrow the potential detecting components.

alt text


This element allows attaching another link to the actual link when it is detected by the raycasts. It is a useful and computationally cheap way to implement grippers for example.



Step_time Use it only when the behavior needs to be run regardless input changes. Consider that the step_time can be changed during runtime so can be set during a period of time or under some circumstances and then reset again.



Names need to be valid python identifiers! Use names that easily relate to the elements that are connected to, for example replacing “.” by ‘“_”. I.e. X1_voltage to refer X1.voltage

Double check the variables with the attribute public=”true”, reserved to parametrize the behavior or provide significant output information.

Do not use behavior variables for internal logic variables (Cleanup debugging variables), declare them internally in the script.

Use helper methods to work with euler and quaternions.