Simutrans Blender Kit v0.3.0 — create sprites, .dat files and .pak objects from Blen

[victor_18993]

Simutrans Blender Kit — a modern Blender workflow for creating Simutrans objects
Simutrans Blender Kit is an add-on for modern Blender versions, from Blender 4.2 onwards. Starting from a 3D model, it can generate the assets Simutrans needs to use that object: directional sprites, sprite sheets and a compilable .dat file.
The add-on also preserves Simutrans' reserved colours exactly, including player colours, transparency colours and signal lights. When MakeObj is configured, the workflow can continue all the way to compiling a .pak and installing it into a pakset's addons directory without leaving Blender.
Download the latest release:
https://github.com/Dkijas/simutrans-blender-kit/releases/latest]https://github.com/Dkijas/simutrans-blender-kit/releases/latest[/url]
The traditional 3D workflow for Simutrans still depends heavily on old forum discussions, wiki pages, manually written .dat files and rigs created for Blender 2.79 and Blender Internal.
Those tools and templates made an enormous amount of existing Simutrans content possible, and this project is not intended to dismiss or replace that work. However, they are difficult for a new artist to adopt using Blender 4.x or 5.x.
For example, pak64 currently provides no modern Blender vehicle template that a new artist can open and use directly.
Simutrans Blender Kit is a greenfield attempt to lower that barrier and turn object creation into a more reproducible workflow. It is currently focused primarily on pak64 and pak128.
The main design principle is that the geometry and generated files should not depend on guesswork. Camera settings, projection, directions, alignment and .dat output are derived from the Simutrans source code and checked against real pakset objects, automated tests and the running game.
What the kit can create
The panel currently supports the following object types:

• Vehicles
  Generates four or eight directional sprites, a sprite sheet and a vehicle .dat.
  Cargo variants are supported, allowing a wagon to display different graphics when empty or when carrying a specific good.
• Buildings
  Supports footprints, height slices, layouts, animation phases and seasons, using the same image structure expected by the engine.
  The building workflow also covers stations, depots and extension buildings, including waytype and accepted goods where applicable.
• Ways
  Supports roads, railways, canals and similar infrastructure.
  The sixteen ribi combinations are generated from six modelled pieces:
  
  • empty
  • end
  • straight
  • curve
  • junction
  • crossing
  Slope images can also be generated for hills.
• Catenary and other way objects
  Supports overhead lines and similar infrastructure.
  The artist can separate objects into backimage and frontimage layers, allowing masts and distant wires to appear behind a vehicle while the contact wire is drawn in front of it.
• Signs and signals
  Generates four directional views and multiple signal states.
  The state and direction order follows the one used internally by Simutrans, including state 0 as the red or danger aspect.
• Tunnels
  Generates portals in four directions with separate back and front image layers.
• Bridges
  Supports spans, ramps and pillars in two image layers, together with bridge properties such as maximum length, maximum height and pillar limits.
• Factories
  Combines a building with factory-specific data, including production, consumption, productivity and minimap colour.

Supporting tools
The add-on also includes several tools intended to catch problems before an object reaches the game.

• Reserved-colour preservation
  Player colours and other special colours are preserved byte-for-byte.
  This requires a dedicated rendering path because Blender's normal colour management and dithering can silently alter the exact RGB values required by Simutrans.
• Pakset profiles
  Profiles are available for pak64 and pak128, with additional profile slots for pak192 and pak256.
  Where possible, values are read from the pakset's own configuration rather than being hard-coded.
• .dat linter
  The included linter detects problems that MakeObj may accept even though they can later cause incorrect behaviour or prevent the game from loading the object correctly.
  It currently checks for issues such as:
  
  • end-of-line comments that Simutrans does not actually treat as comments;
  • indented keys that the parser silently ignores;
  • duplicate keys;
  • unknown keys;
  • valid keys used on the wrong object type;
  • missing build icons;
  • invalid integer values;
  • missing or inconsistent image definitions.
• MakeObj integration
  The generated .dat can be compiled directly from the Blender panel.
  The resulting .pak can optionally be copied into a configured pakset addons directory.
• Automated testing
  The test suite exercises the workflow through Blender, MakeObj and a headless Simutrans build.
  The aim is to verify not only that files are generated, but also that the resulting objects are accepted and behave correctly inside the game.
• English and Spanish interface
  The panel follows Blender's own interface language setting. No separate language option is required inside the add-on.

Why the generated output should be trustworthy
Several parts of the Simutrans rendering workflow are easy to get almost right while still producing visible alignment or direction errors.
The kit attempts to pin these details down explicitly.

• Projection
  The camera reproduces Simutrans' 2:1 dimetric projection using an orthographic view at exactly 30 degrees of elevation.
  Automated tests compare the projected coordinates against the engine's own screen-coordinate calculations.
• Ground alignment
  The ground plane is positioned at three quarters of the image cell height rather than in the centre.
  This was measured against existing pak128 graphics so vehicles and other objects sit correctly on the track or road.
• Coordinate system
  Simutrans uses a left-handed world coordinate system, while Blender uses a right-handed one.
  The kit therefore uses a specific axis convention in Blender:
  
  Code Select Expand
  +X = East
+Y = North
-X = West
-Y = SouthThis avoids reflected curves, reversed building layouts and incorrectly connected infrastructure.
• Directions
  Vehicle and sign directions were checked against objects that already ship in pak128, in addition to being derived from the source code.
• Reserved colours
  Reserved RGB values are checked after rendering and again through the compiled output, ensuring that they survive the complete process rather than only appearing correct inside Blender.

The complete derivations, source-code references and test descriptions are available in the project README.
Typical workflow
A basic vehicle workflow looks like this:

• Create or import the model in Blender.
• Place the model on z = 0 and centre it on the world origin.
• Orient it according to the object convention. For vehicles, the front points along +X.
• Build or configure the Simutrans rig from the panel.
• Render the required directions or object variants.
• Generate the sprite sheet and .dat file.
• Validate reserved colours and run the .dat linter.
• Compile the object using MakeObj.
• Install or test the resulting .pak in Simutrans.

Some object types require specific collections or naming conventions.
For example:

• ways use six collections representing the base ribi shapes;
• catenary can use separate front and back collections;
• signals require a callback or configuration for each state;
• seasonal buildings require the model to be changed before each season is rendered.

These conventions are documented in the repository and demonstrated in the example scripts.
Installation

• Download simutrans_blender_kit.zip from the latest release.
• Open Blender.
• Go to Edit → Preferences → Add-ons.
• Select Install from Disk.
• Choose the downloaded ZIP file.
• Enable the add-on if Blender does not enable it automatically.
• Press N in the 3D View and open the Simutrans tab.

To compile a .pak, MakeObj must also be available.
MakeObj is not distributed inside the add-on. It can be built from the Simutrans source tree:

Code Select Expand

cmake --build --target makeobjAfter building it, select the MakeObj executable from the add-on panel.
You can also configure a pakset addons directory so compiled objects are installed automatically.
Repository:
https://github.com/Dkijas/simutrans-blender-kit]https://github.com/Dkijas/simutrans-blender-kit[/url]
Latest release:
https://github.com/Dkijas/simutrans-blender-kit/releases/latest]https://github.com/Dkijas/simutrans-blender-kit/releases/latest[/url]
Documentation:
https://github.com/Dkijas/simutrans-blender-kit/blob/main/README.md]https://github.com/Dkijas/simutrans-blender-kit/blob/main/README.md[/url]
Current project status
The current automated test results include:

• Core test suite
  1,145 checks currently pass in the Blender-independent part of the project.
  These cover areas such as projection, directions, reserved colours, sheet generation, pakset profiles, .dat generation and linting.
• Blender end-to-end pipeline
  The complete model-to-output workflow is tested with Blender 5.1:
  
  Code Select Expand
  model → directional sprites → sprite sheet → .datThe result is a compilable Simutrans object.
• Add-on installation test
  The automated suite builds the installation ZIP, installs it into Blender, enables the add-on and operates the buttons exposed by the panel.
• In-game vehicle validation
  A generated vehicle is compiled, loaded into Simutrans, found in the depot catalogue, purchased and run on the map.
• Building validation
  Generated buildings are loaded and placed on the map using the engine's own tools.
• Infrastructure validation
  Generated infrastructure is not checked only visually. For example, catenary is queried through the game engine to confirm that the underlying way is genuinely electrified.
• Multi-car convoy tests
  A Civia S/465 and a Madrid Metro Series 9000 have been assembled from several coupled one-tile vehicles and tested on pak128 track and catenary.
  This verifies coupled vehicle formations, but it is different from supporting a single vehicle whose body occupies several tiles.

Current limitations

• Single vehicles longer than one tile
  A single vehicle whose body occupies more than one Simutrans tile is not currently supported.
  Convoys made from several individual one-tile vehicles do work.
• Livery schemes
  Base Simutrans supports cargo or freight image variants, and those are implemented.
  The livery-scheme system available in Simutrans-Extended is outside the current scope of the project.
• pak192 and pak256 profiles
  Profile entries exist, but they currently use engine defaults because I do not have those paksets mounted and measured.
  Feedback from artists using those scales would be particularly useful.
• Real-train demonstration models
  The Civia and Madrid Metro demonstration models are used for development and local testing.
  They are not currently included as generally reusable licensed artwork. See LICENSING.md for the exact status.

Feedback I am looking for
This project is still evolving, and criticism from people who create or maintain paksets would be extremely useful.
I am particularly interested in feedback about:

• whether the workflow is understandable for someone creating their first Simutrans object;
• which steps still feel too technical or require too much manual setup;
• which object types or missing features should receive priority;
• specific requirements of pak64, pak128 and other paksets;
• problems with orientation, scale, alignment or collection naming conventions;
• incorrect or incomplete generated .dat files;
• errors that the linter should detect but currently does not;
• real objects that would make useful automated test cases;
• artists or developers interested in testing the workflow or contributing to the project.

I do not claim that this replaces existing pakset templates or solves every part of Simutrans object creation.
It is an attempt to provide a modern, reproducible and better-documented workflow that can be improved through real use and feedback from the community.
License
The add-on code is released under the MIT License.
Example models and artwork may have different licensing conditions. The two real-train demonstration models are not currently distributed as reusable licensed artwork.
Please consult LICENSING.md in the repository before reusing any example assets.

[victor_18993]

[EN]

Changes compared with the currently published version

Couplings

Published version:
The add-on always generated:

Code Select Expand

Constraint[Prev]=none
This prevented the vehicle from coupling to anything else.

Corrected version:
No coupling constraints are generated by default.

Constraints are now optional and are intended only for fixed units or closed formations.


Lighting

Published version:
Sun energy was set to 10, causing clipped whites, while the world strength of 0.05 produced nearly black shadows.

Corrected version:
Sun energy has been reduced to 3.2, proper ambient world lighting is used, and [tt]make_paint_material[/tt] creates materials with usable surface shading.


Night lights

Published version:
There was no dedicated support for illuminated windows or headlights.

Corrected version:
The add-on now uses [tt]colors.LIGHTS[/tt] and the engine's special light-colour table.

Windows and headlights automatically illuminate at night.


Textures

Published version:
There was no texture system.

Corrected version:
Textures are generated through code, use [tt]Closest[/tt] sampling, and include a separate mask so light colours remain exact.


Reserved colours

Published version:
Only manual validation was available.

Corrected version:
The generated spritesheet is checked automatically, distinguishing deliberately painted reserved colours from accidental occurrences.


These changes improve compatibility with normal Simutrans vehicle formations, produce more readable pak128 sprites, and preserve the exact special colours required by the engine.

I am preparing complete Civia train examples generated with the corrected version so that the results can be evaluated directly in the game.

[victor_18993]

[EN] :estrella: :risa: :estrella:



Renfe Civia S/465 para pak128
Unidad de cinco vagones de Cercanías de Madrid creada completamente con el complemento Blender.

Este es el primer tren completo que he creado de principio a fin utilizando el complemento de Blender que presenté anteriormente en este hilo.

Ese es el hito principal: el complemento ya no es solo una demostración técnica. Ahora puede generar un tren completo y funcional para Simutrans.

Descarga e instalación

Code Select Expand

CiviaS465.pak

Copia el archivo a:

Code Select Expand

<your Simutrans folder>/addons/pak128/

El tren aparecerá entonces en el depósito ferroviario pak128.

Composición

La unidad utiliza la siguiente formación fija de cinco vagones:

Code Select Expand

A – 1 – P – 3 – B

- A: coche de tracción delantera
- 1: remolque intermedio
- P: intermediate car with pantograph
- 3: intermediate trailer
- B: rear driving car

The coupling constraints are configured so that one click on the front driving car automatically assembles the complete five-car unit in the correct order.

The individual cars cannot be combined into unintended formations.

Current vehicle data

- Electric multiple unit
- Maximum speed: 120 km/h
- Capacity: 997 passengers
- Introduction year: 2004
- Fixed five-car formation

The purchase price and running costs are still provisional. Feedback from experienced pak128 balancers would be very welcome.

What I learned while building it

These are the details that required the most investigation, because they are either undocumented or easy to misunderstand.

1. The windows illuminate at night without a separate night sprite

This is not a render effect.

Simutrans uses a day-colour table and a night-colour table for its reserved light colours. The engine gradually transforms one into the other as the world becomes darker.

The relevant implementation can be found in:

Code Select Expand

display/simgraph16.cc

The match must be exact.

For example:

Code Select Expand

RGB(87, 101, 111)

is one of the special window colours and becomes a warm illuminated colour at night.

A visually similar colour such as:

Code Select Expand

RGB(86, 92, 100)

is not recognised as a reserved colour and remains dark.

The Civia deliberately uses a mixture of:

- panes painted with the engine's special window colour;
- panes painted with an ordinary grey.

This prevents the complete window band from becoming one continuous and unrealistic glowing stripe.

2. Vehicles do not have separate night images

A Simutrans vehicle does not use a separate night sprite.

There is no vehicle light-image or night-image key in:

Code Select Expand

vehicle_desc.h

Therefore, a driving car cannot dynamically change between white headlights and red tail lights depending on whether it is leading or trailing the convoy.

The sprite remains the same in both positions.

For that reason, each cab front contains both white headlights and red tail-light lenses, representing the equipment physically present on the real cab.

3. The rear driving car must be modelled facing backwards

The engine renders every vehicle in the convoy using the image associated with the convoy's current direction of travel.

If both cab cars are modelled facing forwards, the rear cab will also appear to point forwards.

The rear driving car must therefore be created as a separate reversed model.

This is also the approach used by existing pak128 vehicles such as:

Code Select Expand

BR-373_FrontCar
BR-373_BackCar

4. All five cars use length=8

This was the most time-consuming issue to diagnose.

My first implementation converted the real module lengths into different Simutrans length values.

The physical module lengths used were approximately:

- 22.4 m
- 17.75 m
- 20.75 m
- 14.75 m

These produced Simutrans length values of:

Code Select Expand

14, 11, 13 and 9

The result was a visible gap behind every longer car.

The reason is that the engine positions each vehicle behind the previous one using the length of the previous vehicle, while the artwork itself remains centred inside its sprite cell.

Con longitudes de vehículos mixtas, la junta visible cambia aproximadamente según:

Code Select Expand

(previous length - current length) / 2

El desplazamiento previsto fue:

Code Select Expand

+6.7 px, -4.5 px, +8.9 px, -11.2 px

El desplazamiento observado coincidió con esos valores.

Luego revisé varios vehículos ferroviarios pak128 existentes. Todos los ejemplos que probé utilizan:

Code Select Expand

length=8

Esto incluía los vagones de las series ACE3-407, Thunder, Eurostar, Clase 2000 y el automotor 620.

Por lo tanto, el Civia también utiliza la longitud 8 para los cinco coches.

La solución de compromiso consiste en que las diferentes longitudes de los módulos reales no se representan con exactitud en el espaciado del convoy. Sin embargo, esto produce un tren visualmente continuo y sin interrupciones, lo cual es preferible a mantener longitudes internas desiguales y, al mismo tiempo, romper la apariencia de la unidad completa.

Validación dentro de Simutrans

El tren no fue validado únicamente a través de renders o archivos generados.

Se probó dentro de un juego pak128 en ejecución:

- La unidad aparece en el catálogo del depósito ferroviario;
- Un solo clic ensambla los cinco coches en el orden correcto;
- Las restricciones impiden formaciones no válidas;
- El tren está identificado como eléctrico;
- funciona correctamente bajo la catenaria pak128;
- Las ocho direcciones se visualizan correctamente;
- Los colores de la luz de la ventana se activan por la noche;
- El convoy completo funciona como un vehículo operativo, no simplemente como una maqueta visual.

Todas estas conclusiones proceden del código fuente de Simutrans o de pruebas directas realizadas en el juego.

Limitaciones actuales

- El precio de compra y los costes de funcionamiento son provisionales.
- Las diferentes longitudes físicas de los coches reales se representan de forma aproximada visualmente.
- Los faros delanteros y traseros no pueden cambiar dinámicamente entre la cabina delantera y la trasera porque los vehículos Simutrans no admiten estados de iluminación direccionales separados.

El tren completo de cinco vagones está adjunto y puede probarse libremente.

Si este ejemplo le resulta útil, no dude en utilizarlo.

Y si deseas crear un tren diferente, el complemento de Blender es la herramienta que produjo este.

[victor_18993]

## Release v0.3.0 is now available

The first public downloadable release of the Simutrans Blender Kit is now available:

https://github.com/Dkijas/simutrans-blender-kit/releases/tag/v0.3.0

Users no longer need to clone the repository or build the add-on manually.

Download:

    simutrans_blender_kit.zip

Then install it in Blender through:

    Edit → Preferences → Add-ons → Install from Disk

Select the downloaded ZIP and enable the add-on. The Simutrans panel will appear in the
3D View sidebar.

### What has changed since the first forum version

- Player-colour, shaded-paint and night-light materials are now available directly from
  the Blender panel.
- Model clipping and accidental reserved colours are reported visibly in the interface.
- `.dat` files can be regenerated without rendering the sprite sheet again.
- Ways and catenaries now generate the required slope images.
- The standalone linter validates numeric values and gives every diagnostic a stable code.
- The linter supports JSON output and local suppressions using:

      # bkit: ignore=<code>

- The test harness locates Blender, makeobj and Simutrans instead of assuming fixed
  Windows paths.
- The project is now maintained in Git with an MIT licence, changelog and versioned test
  scenarios.
- Generated release packages are checked before publication.
- The README now contains the real validation results and correct artwork credits.

The release contains 20 files and can be installed directly in Blender.

This is the best version to test. Feedback from vehicle artists, pakset authors and Linux
or macOS users would be especially useful.

Repository:

https://github.com/Dkijas/simutrans-blender-kit

Release:

https://github.com/Dkijas/simutrans-blender-kit/releases/tag/v0.3.0