Simutrans Blender KitSimutrans Blender Kit is an add-on for modern Blender versions that helps artists create Simutrans objects without having to build the entire export workflow manually.
Starting from a Blender model, the kit can prepare the scene, render the required directions, create sprite sheets and DAT files, validate the result and compile a .pak when MakeObj is configured.
What it can help you create- Vehicles and complete train formations
- Buildings, stations and depots
- Ways, catenary and other infrastructure
- Signs, signals, tunnels, bridges and factories
It also includes tools for reserved colours, coupling constraints, object variants, eight-direction previews, DAT validation and project packaging.
Getting startedDownload the latest release here:
Latest Simutrans Blender Kit release (https://github.com/Dkijas/simutrans-blender-kit/releases/latest)
In Blender, open:
Edit → Preferences → Add-ons → Install from DiskSelect the downloaded ZIP and enable Simutrans Blender Kit.
Then press
N in the 3D View and open the
Simutrans tab.
Documentation and sourceFull instructions, supported workflows and technical details are maintained on GitHub:
Project repository (https://github.com/Dkijas/simutrans-blender-kit)
Documentation (https://github.com/Dkijas/simutrans-blender-kit/blob/main/README.md)
CompatibilityThe current release targets Blender 4.2 and later.
Development and automated testing are currently performed primarily on Blender 5.x and Windows, so feedback from Blender 4.x, Linux and macOS users is especially useful.
Feedback welcomeThe project is intended to make creating Simutrans objects easier for both new and experienced artists.
Reports about installation, usability, generated DAT files, alignment, pakset-specific requirements or missing features are very welcome.
Release-specific changes and downloads are posted in the replies below.
[EN]
Changes compared with the currently published version
Couplings
Published version:
The add-on always generated:
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.
[EN] :estrella: :risa: :estrella:
civia prueba.png
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
CiviaS465.pak
Copia el archivo a:
<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:
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:
display/simgraph16.cc
The match must be exact.
For example:
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:
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:
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:
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:
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:
(previous length - current length) / 2
El desplazamiento previsto fue:
+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:
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.
## 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
Simutrans Blender Kit 0.10.0This release brings together the work from versions 0.8, 0.9 and 0.10.
Version 0.7 could turn a finished Blender model into a Simutrans .pak file. The kit can now also help you start a project, create complete vehicle families and define how the vehicles form a train.
InstallationDownload simutrans_blender_kit.zip attached below.
In Blender, go to:
Edit → Preferences → Add-ons → Install...Select the ZIP file and enable Simutrans Blender Kit.
What is new- Create Template prepares the collections, scale, orientation and naming required by the exporter.
- Consist Manager lets you define complete formations, including head vehicles, intermediate cars, optional vehicles, repeatable sections and reversible trains. It then derives the required Simutrans coupling constraints.
- Show Constraints displays the proposed changes before writing anything.
- Variants creates separate Simutrans objects for different liveries or versions of the same vehicle.
- Eight-direction preview renders every required direction using the same camera and lighting as the final export.
- Component catalogue provides generated wheelsets, bogies, pantographs, headlights and couplers as starting points. They are created from Blender primitives and include no third-party artwork.
- Project packaging creates a ZIP containing the DAT files, sprites, licence and a manifest with checksums. Nothing is uploaded automatically.
Coupling constraints correctedThe previous version described none and any incorrectly in parts of the interface.
The new implementation follows the actual behaviour of Simutrans:
No constraint may appear anywhere
none may only appear at the head
any must have another vehicle in frontThe Consist Manager now derives these rules from the formations you define, instead of asking the artist to calculate them manually.
A more detailed technical explanation is included in:
docs/constraints-in-simutrans.mdExample projectsThe Metro 9000 data has been corrected, and its per-car totals are now validated automatically.
The editable source for the Metro 7000 is also included under the CC BY 4.0 licence, allowing others to rebuild and modify the published vehicle.
TestingAll 45 test suites pass, covering the core tools, Blender pipeline, makeobj compilation and loading in pak128.
The preview frames are also checked against the final exported renders, and the coupling system has been tested with optional cars, repeatable sections, reversible formations and vehicles used in several formations.
Current limitationsThe release was developed and tested with Blender 5.1.2 on Windows.
Blender 4.2 and later are the intended supported versions, but Blender 4.x, Linux and macOS have not yet been tested directly.
Feedback and test results from other Blender versions and operating systems are very welcome.