Documentation

GardenTrains developer's technical documentation, writen by Quintus Hegie for computer geeks. With this documentation you'll be able to develop new levels and create new game objects (locomotives and/or wagons). If you're a web developer and you have a question about 3D progamming and/or BabylonJs, please contact me on HTML5GameDevs. If you're a game player instead of a developer, then you can find the manual here.

Please note: The game specific soure code is protected with legal copyright! You may not use this code to create your own train or similar game, but you can use some components and logic for any other type of game. The code may be changed at any time without any notification, rendering any custom additions maybe no longer compatible with the latest version.

3D Engine

Scene Optimization

In comparison with regular train simulator games with large worlds that are partly visible, my game is about model trains where the whole play world fits into a single room so to say. The player thus generally has a good camera view over the whole level (room). Therefore most meshes are visible and need to be rendered most of the time. This creates a challenge for keeping a constant and high framerate, because only a little fraction of the meshes will be out of view most of the time. That is why I use some specific scene optimization techniques for this train game.

Level of Detail (LOD)

A level mainly consists of a terrain or playing ground, that is visible in full or in large part. Next in line of frequently visible meshes are the train tracks. The train tracks may be observed from very close by (when camera is set to train drivers view mode) as well as from a large distance (when camera is set to level map view). A technique to speed up rendering when using various distances to view the same mesh is to apply Level of Detail (LOD).

Levels of Detail on a Rail: left the full mesh (rendered when viewed from close-by), right the simplified mesh (rendered when viewed from a distance)

Game Engine

General logic

Config file

The game consists of many different game object types, which each have their own unique capabilities. To keep the game logic as simple as possible, I chose to use a config or settings file to set up a specific game object type.

This config file contains the properties to set for the different game objects. This way it would be easier for me to tweak the game settings in order to get the best gaming experience. The specific game object's type config will be loaded in the GameObject definition from the settings file.

Game Objects

Hierarchy

Locomotives

A locomotive is equiped with a motorblock and is controllable by a player.

Locomotive Game Object: accessors of attached objects

Wagons

A wagon is not motorized and needs to be pushed/pulled by a locomotive.

Wagon Game Object: accessors of attached objects

Trains

A train is a logical unit that consists of one or more vehicles (array). Because this is a train game, the vehicles in a train are typically rail vehicle game objects like wagons and locomotives. A train has at most 1 master, that is the unit that controls or moves the train (often the 1st locomotive).

Train Game Object: accessors of attached objects and constraints

A train vehicle sequence imposes a new (additional) constraint on its vehicles. Where a wagon and/or locomotive is already rail track bound by its wheels, a train also is bound to the condition that the vehicles are attached to each other. The separate vehicles together form a whole 1 train.

The constraint added is that the distance between each coupling is limited by a min and max hook 'rope'. This is of course a simplification of the physical constraint for real world model trains (as hooks aren't ropes but rigid bodies), but it gives enough effect of a train composition because the vehicles are bound to the rail track anyway. As rail tracks won't make sudden abrupt 90-degree angles, but only slow smooth curves, the 'rope' constraint will give nice enough visual impression of inter-wagon connection.

Trainline system

The tracks within the game are laid out within the trainline system. Each segment within the TrainLineSystem is called a TrainLine.

Laying railroad track

Railroad track is layed very similar to the construction of a toy model railroad layout: consecutively by connected each train peace to the next. Railroad track is then layed using track pieces. The order of the track laying must respect the natural driving direction. The following track pieces are available:

A starting track (for example a buffer stop) can be given a starting position and rotation. Any next connected track will be layed in the specified direction.

Turnouts

Turnouts are logical units and don't have a track size (length) themselves, so you must connect straight or curved tracks yourself. All turnouts must have an unique id each so the track layer knows which tracks to connect where to it in what direction. Based on the entry and exit-points, tracks are connected to the turnouts. For example, the leftturnout has connecting points start, left and straight.

Power connectors

Power connectors are logical units and don't have a track size (length) themselves. You cannot start or end track with a a powerconnector; it must be placed within a track segment. If a team is specified, the powerconnector becomes a possible starting location for any player in that team. If a player is specified, the powerconnector becomes the starting position for that player locomotive.

Trigger magnets

Trigger magnets are logical units and don't have a track size (length) themselves. You cannot start or end track with a a powerconnector; it must be placed within a track segment. If a group is specified, the triggermagnet will trigger any logic tied to that group. For example, you can open or close a bridge, a gated level crossing, change a signal, etc.

Crane

A crane is equiped with a hook and one or more controllable joints. The controllable joints allow for steering and operation of the crane.

Crane Structure Game Object: accessors of attached objects

The joints can be restricted so that movement or rotation is limited to a certain distance or angle for example by setting the min and max properties.

Places & Zones

In the game, places and areas of interest and interaction are marked by the logical Place and Zone GameObjects. Both a Place and a Zone have a position and a rotation, but only a Zone has a scaling attribute.

The usage of places and areas enables interaction in the level for moveable GameObjects. For example for a Vehicle (including locomotives and wagons) and a Creature (including figures), but also for Item (such as goods). Both a Place and a Zone trigger an action on moveable GameObjects entering and/or leaving the marked location or area.

A difference between a Place and a Zone is that an occupant bounding box need not fit in a Place, but must fit as a whole in a Zone.

Places

A Place has no shape because it only marks a location. The rotation may indicate at which direction the occupant must occupy the place.

We defined a special set of Places that mark some standard location automatically. The special Places are:

Zones

A Zone has either a box or sphere shape to describe the size of the area. The shape also determines the colission detection to use for GameObject models entering and exiting the area.

The default size of the Zone is Babylon.Vector3.One().

Use the GameObject parenting system to attach a Zone to a (often static) GameObject such as a Structure.

We defined a special set of Zones that accomplish some standard task automatically. These types of Zones also show visible markers, so their presense and usage is more clear to the Player. The special Zones are:

Level setup

The Level GameStateObject creates the playfield (scene) for your trains based on the level config file in JavaScript (which is included in the specific level HTML).

Level config file (JavaScript)

First set the general properties of the level:

Property: level
PropertyMeaningExample
iLevel number (higher level number means more complex level to complete)1
nameUnique internal level name'gardentrainsdemo1'
titleA friendly title for this level, shown to player'Garden Trains Demo Level #1'
descriptionA longer description for this level, shown to player'A demo level of garden trains consisting of a basic circle railway track layout.'
authorName of the level author/creator'Conduqtor Q'
locationGeographical location of the level, for example a place name and a country name (especially used for outdoor track layouts)'Rotterdam, The Netherlands'
urlAn optional URL to a webpage containing more information on the level for background reading at another time'https://quintushegie.com/gardentrains'

Second, construct the empty world (that will later contain the model train tracks):

Property: world_config
PropertyMeaningExample
terrainTextures for the terrain. 
heightmapOptional. Set it to give the terrain a heightmap. 
groundSets the size of the playground (where the train track is put upon). 
tiledOptional. Set it to place a tiled floor under the model train ground. Great for indoor scenes. 
sun

Optional. Configures the lighting for the scene.

You can set the type of lighting with type. Choose from: HemisphericLight (great for debugging), PointLight (great for indoor scenes), DirectionalLight (great for outdoor scenes) and SpotLight (great for mini-scenes). The scene will always be lit with at least a HemisphericLight.

You can optionally set the time with time. It can set the scene's lighting to a fixed time in day (midnight, night, dusk, morning, day, noon, afternoon, evening, dawn, night), or simulate a day/night schedule with setting clock (24 hours pass in 6 minutes, starts at day).

 
sky Optional. Configures the skybox for the scene. { 'url': 'sunny' }
waterOptional. Adds a full-scale water to the level. 

Third, place the railway tracks:

track_line_layout (more info soon)

Fourth, add all other objects to complete the scene:

Finally, decide upon the mission objectives to complete the level:

objectives