Difference between revisions of "MXB Track Creation Guide"

From PiBoSo Documentation
Jump to navigation Jump to search
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''[http://www.mx-bikes.com/downloads/mxb_track_example.zip Download the example track files]'''
'''[http://www.mx-bikes.com/downloads/mxb_track_example.zip Download the example track files]'''
<br/><br/>
'''Basic Workflow'''
 
*[[#Heightmap|Create Heightmap]], saw as IBM .RAW
==Basic Workflow==
*[[#Heightmap|Create Heightmap]], save as 16-bit .raw
*[[#track.hmf|Create texture map]], assign to a texture layer in the hmf file and check terrain sizes & scaling
*[[#track.hmf|Create texture map]], assign to a texture layer in the hmf file and check terrain sizes & scaling
*[[#Terrained|Run map.bat]] (terrained + source files must be in the same folder) to generate .map file
*[[#Terrained|Run map.bat]] (terrained + source files must be in the same folder) to generate .map file
Line 9: Line 10:
*[[#TrackEd|Open trh in TrackEd]], create a centerline, merge and save trh
*[[#TrackEd|Open trh in TrackEd]], create a centerline, merge and save trh
*Use [[TrackEd]] to create all track data files
*Use [[TrackEd]] to create all track data files
<br/>
----


==Heightmap==
==Heightmap==
:Heightmap must be '''16bpp 2049x2049 IBM RAW'''.
:Heightmap must be '''16bpp IBM RAW'''.
:1025x1025 & 4097x4097 are also supported.
:The heightmap dimensions must be a power of 2 +1. 2049x2049 is recommended. Rectangular heightmaps are supported; for example, the straight rhythm heightmap is 4097x257!


==Track Data files==
==Track Data files==
Line 30: Line 29:
   
   
  layer0
  layer0
  (
  {
  '''map''' = track.tga ''(for example, the base terrain texture name)''
  '''map''' = track.tga ''(for example, the base terrain texture name)''
  '''repetitions''' = 1 ''(texture tiling)''
  '''repetitions''' = 1 ''(texture tiling)''
Line 40: Line 39:
  '''repetitions''' = 50 ''(if you are using a shader for this texture, this value should match the one in the .shd file)''
  '''repetitions''' = 50 ''(if you are using a shader for this texture, this value should match the one in the .shd file)''
  '''mask''' = grass_mask.tga ''(the alpha channel will be a mask that shows / hides this layer)''
  '''mask''' = grass_mask.tga ''(the alpha channel will be a mask that shows / hides this layer)''
'''thickness''' = 0.1 ''(the layer thickness, in meters)''
   
   
  '''grass''' ''(enables 3d grass for this layer)''
  '''grass''' ''(enables 3d grass for this layer)''
Line 52: Line 52:
   }
   }
  }
  }
scene0 (here you add the scenery model)
{
'''name''' = scenery.edf ''(name of the scenery model file)''
'''pos''' ''(use these values to change the position and rotation of the scenery)''
{
x = 0
y = 0
z = 0
}
'''rot'''
{
x = 0
y = 0
z = 0
}
}
If different texture tiling is needed on the X and Z axes, "repetitions" must be replaced with, for example:
'''repetitions_x''' = 1
'''repetitions_z''' = 2


===track.tht===
===track.tht===
Line 62: Line 83:
  '''size_z''' = 480 ''(must be the same as value in .hmf file)''
  '''size_z''' = 480 ''(must be the same as value in .hmf file)''
  '''scale''' = 3.2 ''(must be the same as value in .hmf file)''
  '''scale''' = 3.2 ''(must be the same as value in .hmf file)''
'''num_surface_layers''' = 3 ''(surface layers define different areas on your track)
surface_layer0
{
'''surface''' = off ''(This defines the offtrack areas)''
'''mask''' = area_off.tga
}
surface_layer1
{
'''surface''' = pit ''(This defines the pit)''
'''mask''' = area_pits.tga
}
surface_layer2
{
'''surface''' = start ''(This defines the start gate area)''
'''mask''' = area_start.tga
}
'''num_material_layers''' = 3 ''(material layers define the track physics surfaces. You can also use masks, like in the hmf file)
material_layer0 (the base layer, doesn't need a thickness)
{
'''material''' = compact soil
}
material_layer1
{
'''material''' = soil
'''thickness''' = 0.1
}
material_layer2
{
'''material''' = soft soil
'''thickness''' = 0.1
}
   
   
  scene0 ''(here you add the scenery model)''
  scene0 ''(here you add the scenery model)''
Line 79: Line 139:
  }
  }
  }
  }
====Material Layers====
Due to the dynamic track surface in MXB, bikes will 'dig through' the material layers over time. In the above example, the top layer is soft, loose soil. Just underneath is regular soil, and then the bottom layer is a compact soil. This generally works best as the softer soils erode faster. Each material type has unique grip characteristics, and generates it's own particle effects.
You can also have material types '''sand''' and '''gravel'''.


==Terrain Textures & Shaders==
==Terrain Textures & Shaders==
Line 89: Line 153:
  bump
  bump
  {
  {
  '''map''' = mud_n.tga ''(normal map filename, specular level should be in alpha channel)''
  '''map''' = mud_n.tga ''(normal map filename, specular level must be in alpha channel)''
  '''repetitions''' = 46 ''(must be the same as the value for this texture layer in the .hmf file)''
  '''repetitions''' = 46
  }
  }
   
   
Line 97: Line 161:
  '''shininess''' = 12 ''(sharpness of the specular highlight)''
  '''shininess''' = 12 ''(sharpness of the specular highlight)''
  }
  }
Please note that if "repetitions" is missing it is automatically set to 1. If, instead, it is explicitly set to 0 then the texture repetitions are used.
===Masks===
If you want to use a tiled ground texture, you can use a mask to specify on which parts of the terrain it should appear.<br/>
The mask '''MUST BE IN THE ALPHA CHANNEL''' of the dedicated mask tga. All colour channels are ignored.<br/>
Then you can assign it to the correct texture layer in the HMF file:<br/>
layer1
{
        map = mud.tga
        repetitions = 50
        mask = mud_mask.tga
        thickness = 0.1
}
The base layer ('''layer0''') should not have a mask.


==TerrainEd==
==TerrainEd==
Line 116: Line 195:
  '''shadowmaps_scale''' = 0.2 ''(can usually be left at 0.2)''
  '''shadowmaps_scale''' = 0.2 ''(can usually be left at 0.2)''
  '''shadowmaps_supersampling''' = 4 ''(quality of the shadow volumes, reduce for faster exports)''
  '''shadowmaps_supersampling''' = 4 ''(quality of the shadow volumes, reduce for faster exports)''
'''shadowmaps_terraincast''' = 1 ''(the terrain self-casts shadows)''


*Run '''map.bat''' to generate a track.map file
*Run '''map.bat''' to generate a track.map file
Line 129: Line 209:
*For instructions on using TrackEd, go here: [[TrackEd]]
*For instructions on using TrackEd, go here: [[TrackEd]]


==Extra Files==
==Environment Sounds==
*If desired, you can adjust the sun position & colour, fog amount & colour, and ambient light colour, for all conditions. Open the .amb file in notepad, and use [[Map Viewer]] to see the changes. Please note that you should use the same settings for the sun direction in the amb file and the params.ini file.
It is possible to place sounds sources around a track, creating a text file with SSC extension in the track folder.
numsources = 3
source0
{
      data = *crowd.wav
      pos = 0,0,0
      mindistance = 10
}
source1
{
      data = *crowd.wav
      pos = 1,1,1
      mindistance = 10
}
source2
{
      data = test.wav
      pos = 2,2,2
      mindistance = 5
}
''mindistance'' is the distance under which volume is the max.<br/>
Samples must be in '''.wav''' format and mono channel.<br/>
The files must be placed in the track folder.
If the filename has a '''*''' prefix, then the file must be placed in the '''effects/sounds/''' directory.
 
==.amb file==
You can adjust the sun position & colour, fog amount & colour, ambient light colour, and sky rotation for all conditions. Open the .amb file in notepad, and use [[Map Viewer]] to see the changes. Please note that you should use the same settings for the sun direction in the amb file and the params.ini file.
You can use custom skies if desired by exporting your skydomes in .edf format.
 
==Other Files==
*You should edit the .ini file to change the track name, author, location etc.
*You should edit the .ini file to change the track name, author, location etc.
*Update the track.tga screenshot and the track_map.tga.
*Update the track.tga screenshot and the track_map.tga.
*Use the skies provided, or create new skydomes.


==Packing==
==Packing==
Line 139: Line 247:
:For example, mytrack/
:For example, mytrack/


You should have the following files in the folder:
You should have, at minimum, the following files in the folder:


  mytrack.map ''(track graphics)''
  mytrack.map ''(track graphics)''
Line 145: Line 253:
  mytrack.rdf ''(race data - pits, startgates, finishline etc.)''
  mytrack.rdf ''(race data - pits, startgates, finishline etc.)''
  mytrack.ini ''(track information)''
  mytrack.ini ''(track information)''
mytrack.tsc ''(trackside cameras)''
  mytrack.amb ''(lighting and environment settings)''
  mytrack.amb ''(lighting and environment settings)''
  mytrack_map.tga ''(map of the track for the UI)''
  mytrack_map.tga ''(map of the track for the UI)''
  mytrack.tga ''(screenshot of the track for the UI)''
  mytrack.tga ''(screenshot of the track for the UI)''
  clearsky.edf ''(sunny skydome)''
  gate.edf ''(starting gate model)''
  cloudysky.edf ''(cloudy skydome)''
 
  rainysky.edf ''(rainy skydome'')
 
:The gate edf can be copied from the practice track.
:To test your track in MXB, copy this folder to your '''mods\tracks''' folder
 
Extra files you should include for final tracks:
 
  marshals.cfg ''(trackside marshals placement file)''
mytrack.tsc ''(trackside cameras)''
  checkleft.tl & checkright.tl ''(reset lines at the track edges)''
maxrace.tl & minrace.tl ''(auto-generated for resetting the bike to track)''
 
==Distribution & Registration==
For distribution, '''zip up your track folder''' and rename the zip file to '''.pkz'''. The folder must be zipped, '''not just the files'''. Now users only need to drop the single .pkz file into their mods\tracks folder.
 
You can register your track for online records here:
http://www.piboso.com/trackreg/trackreg.php


:To test your track in MXB, copy this folder to the '''tracks''' folder in the MX Bikes installation directory.
Look in code.txt (in the same folder as your trh file) for your unique track code. You only need to enter 'Prev. Track Code' if you are updating a previously registered track.
:For distribution, you can zip up the folder and rename the zip file to '''.pkz'''. The folder must be zipped, not just the files.
Once successfully registered, do a couple of laps online and your fastest lap should appear in the records: http://stats.mx-bikes.com/records.php

Revision as of 15:51, 13 January 2020

Download the example track files


Basic Workflow

Heightmap

Heightmap must be 16bpp IBM RAW.
The heightmap dimensions must be a power of 2 +1. 2049x2049 is recommended. Rectangular heightmaps are supported; for example, the straight rhythm heightmap is 4097x257!

Track Data files

track.hmf

samples_x = 2049 (RAW image width)
samples_y = 2049 (RAW image height)
data = heightmap.raw (RAW image filename)

size_x = 480 (track size in meters)
size_z = 480 (track size in meters)
scale = 3.2 (total track height in meters)

num_layers = 2 (number of texture layers)

layer0
{
map = track.tga (for example, the base terrain texture name)
repetitions = 1 (texture tiling)
}

layer1
{
map = grass.tga (second texure layer name)
repetitions = 50 (if you are using a shader for this texture, this value should match the one in the .shd file)
mask = grass_mask.tga (the alpha channel will be a mask that shows / hides this layer)
thickness = 0.1 (the layer thickness, in meters)

grass (enables 3d grass for this layer)
 {
 max_density = 8
 height = 0.15
 height_diff = 0.1 (randomise the grass height by this much)
 width = 0.2
 width_diff = 0.1 (randomise the grass width by this much)
 texture = grassfx.tga (this map is split into 4 horizontal sections - so 1024x256 is split into 4 separate 256x256 textures)
 densitymap = mask.tga (alpha channel controls the grass density)
 }
}

scene0 (here you add the scenery model)
{
name = scenery.edf (name of the scenery model file)
pos (use these values to change the position and rotation of the scenery)
	{
	x = 0
	y = 0
	z = 0
	}
rot
	{
	x = 0
	y = 0
	z = 0
	}
}

If different texture tiling is needed on the X and Z axes, "repetitions" must be replaced with, for example:

repetitions_x = 1
repetitions_z = 2

track.tht

samples_x = 2049 (must be the same as value in .hmf file)
samples_z = 2049 (must be the same as value in .hmf file)

data = heightmap.raw (must be the same as value in .hmf file)

size_x = 480 (must be the same as value in .hmf file)
size_z = 480 (must be the same as value in .hmf file)
scale = 3.2 (must be the same as value in .hmf file)

num_surface_layers = 3 (surface layers define different areas on your track)

surface_layer0
{
	surface = off (This defines the offtrack areas)
	mask = area_off.tga
}

surface_layer1
{
	surface = pit (This defines the pit)
	mask = area_pits.tga
}

surface_layer2
{
	surface = start (This defines the start gate area)
	mask = area_start.tga
}

num_material_layers = 3 (material layers define the track physics surfaces. You can also use masks, like in the hmf file)

material_layer0 (the base layer, doesn't need a thickness)
{
	material = compact soil
}

material_layer1
{
	material = soil
	thickness = 0.1
}

material_layer2
{
	material = soft soil
	thickness = 0.1
}

scene0 (here you add the scenery model)
{
name = scenery.edf (name of the scenery model file)
pos (use these values to change the position and rotation of the scenery)
	{
	x = 0
	y = 0
	z = 0
	}
rot
	{
	x = 0
	y = 0
	z = 0
	}
}

Material Layers

Due to the dynamic track surface in MXB, bikes will 'dig through' the material layers over time. In the above example, the top layer is soft, loose soil. Just underneath is regular soil, and then the bottom layer is a compact soil. This generally works best as the softer soils erode faster. Each material type has unique grip characteristics, and generates it's own particle effects. You can also have material types sand and gravel.

Terrain Textures & Shaders

Textures must be in TGA or BMP truecolor format. Size must be power of 2 (256, 512, 1024, 2048, 4096). Textures can be rectangle ( for example: 256x512, 1024x64 )

SHD files

These allow you to use specular & normal maps. Must be named the same as the texture it will be applied to (for example, mud.tga & mud.shd)

bump
{
map = mud_n.tga (normal map filename, specular level must be in alpha channel)
repetitions = 46
}

specular
{
shininess = 12 (sharpness of the specular highlight)
}

Please note that if "repetitions" is missing it is automatically set to 1. If, instead, it is explicitly set to 0 then the texture repetitions are used.

Masks

If you want to use a tiled ground texture, you can use a mask to specify on which parts of the terrain it should appear.
The mask MUST BE IN THE ALPHA CHANNEL of the dedicated mask tga. All colour channels are ignored.
Then you can assign it to the correct texture layer in the HMF file:

layer1
{
       map = mud.tga
       repetitions = 50
       mask = mud_mask.tga
       thickness = 0.1
}

The base layer (layer0) should not have a mask.

TerrainEd

TerrainEd is a command-line program. It is needed to generate a .map (graphics) file and a .trh (collisions) file. Shadows are generated automatically during the .map export. Arguments:

TerrainEd inputfile outputfile [params]

params.ini

Here you can change light / shadows settings.

[params]
lightdir_x = 2 (position of the sun east)
lightdir_y = 10 (position of the sun up [can be left at 10 usually])
lightdir_z = -7 (position of th sun north)
shadowvolumes_create = 1 (enable shadow volumes generation, turn off for faster exports for testing) 
shadowvolumes_supersampling = 4 (quality of the shadow volumes, can usually be left at 4)
shadowmaps_create = 1 (enable shadows generation, turn off for faster exports for testing) 
shadowmaps_scale = 0.2 (can usually be left at 0.2)
shadowmaps_supersampling = 4 (quality of the shadow volumes, reduce for faster exports)
shadowmaps_terraincast = 1 (the terrain self-casts shadows)
  • Run map.bat to generate a track.map file
  • Run trh.bat to generate a track.trh file

Rename these files to your chosen track name.

TrackEd

  • Open your .trh file in tracked.
  • You will need to create a centerline, merge it, and then save the trh.
  • You must place the pits, starting gates, finish line, and pitboards.
  • You can also place marshals and replay cameras.
  • For instructions on using TrackEd, go here: TrackEd

Environment Sounds

It is possible to place sounds sources around a track, creating a text file with SSC extension in the track folder.

numsources = 3
source0
{
     data = *crowd.wav
     pos = 0,0,0
     mindistance = 10
}
source1
{
     data = *crowd.wav
     pos = 1,1,1
     mindistance = 10
}
source2
{
     data = test.wav
     pos = 2,2,2
     mindistance = 5
}

mindistance is the distance under which volume is the max.
Samples must be in .wav format and mono channel.
The files must be placed in the track folder. If the filename has a * prefix, then the file must be placed in the effects/sounds/ directory.

.amb file

You can adjust the sun position & colour, fog amount & colour, ambient light colour, and sky rotation for all conditions. Open the .amb file in notepad, and use Map Viewer to see the changes. Please note that you should use the same settings for the sun direction in the amb file and the params.ini file. You can use custom skies if desired by exporting your skydomes in .edf format.

Other Files

  • You should edit the .ini file to change the track name, author, location etc.
  • Update the track.tga screenshot and the track_map.tga.

Packing

All final track files should go in a folder of the same name.
For example, mytrack/

You should have, at minimum, the following files in the folder:

mytrack.map (track graphics)
mytrack.trh (track collision)
mytrack.rdf (race data - pits, startgates, finishline etc.)
mytrack.ini (track information)
mytrack.amb (lighting and environment settings)
mytrack_map.tga (map of the track for the UI)
mytrack.tga (screenshot of the track for the UI)
gate.edf (starting gate model)


The gate edf can be copied from the practice track.
To test your track in MXB, copy this folder to your mods\tracks folder

Extra files you should include for final tracks:

marshals.cfg (trackside marshals placement file)
mytrack.tsc (trackside cameras)
checkleft.tl & checkright.tl (reset lines at the track edges)
maxrace.tl & minrace.tl (auto-generated for resetting the bike to track)

Distribution & Registration

For distribution, zip up your track folder and rename the zip file to .pkz. The folder must be zipped, not just the files. Now users only need to drop the single .pkz file into their mods\tracks folder.

You can register your track for online records here: http://www.piboso.com/trackreg/trackreg.php

Look in code.txt (in the same folder as your trh file) for your unique track code. You only need to enter 'Prev. Track Code' if you are updating a previously registered track. Once successfully registered, do a couple of laps online and your fastest lap should appear in the records: http://stats.mx-bikes.com/records.php