BallisticNG Scene Structure

This is a page about the Ballistic Unity Tools.

This page covers the topic of how to structure your scenes for custom tracks, where you can find references for setting up the scene and the Track Wizard.

## Import TRM File

Once you have made your track in the Track Creator you will have the option to export a TRM file. The TRM format is simply a mesh stored in the exact same format that it is in when in memory inside Unity.

To import a TRM file into your Unity project all you need to do is copy the file somewhere into your project's asset folder. A prefab and folder will be created. You can ignore the folder, these just contain the raw assets used for the prefab. Once you have the prefab, drag it into a new empty scene and set its position to 0, 0, 0.

## Track Wizard

It is reccomended that you use the Track Wizard to setup your track. You can setup your track without it, but using it will reduce the amount of time needed and will provide you with a structured hiearchy of objects to help keep things tidy. The Track Wizard can be found by going to BallisticNG -> Track Wizard on Unity's menu bar.

If you have followed the instructions on the above segment then the references in the Track Wizard should already be filled out and all you have to do is click run. You might however also want to change the Sun and Ambient colors. Keep in mind though that these two thing are covered over on BallisticNG Vertex Lightmapper.

## Scene References

In order for any custom track to work a scene references script must be present in the scene, if you have just followed the instructions above then you can find this script by navigation to Scene Configuration -> Managers -> Scene References in the hiearchy view.

The options you are presented with are a wather dropdown, track data reference and 4 arrays for various things.

### Weather

This dropdown is as simple as it gets, this allows you to set the type of weather active on the track.

### Type

This dropdown controls the type of track, you can choose from Normal, Drag or Drift. Setting drag will mean that the game treats it as a drag track, both drag and drift also control which ships can be selected when you select that given track.

### Bloom Type

This dropdown controls the bloom prefab that will be used for this track. This controls both bloom and lens effects and are only active if the settings are enabled in the game's options.

**None -** No bloom prefab will be loaded.

**Wet -** Optimized for dim, wet scenes.

**Snowy -** Optimized for bright, snowy scenes.

**Dim -** Optimized for darker tracks.

**Bright -** Optimized for daytime tracks.

**Neon -** Optimized for night-time cities.

### Track Data

This reference field is only useful if you have setup the scene yourself, if you used the Track Wizard then this is already setup and you don't need to worry about this.

### Countdown Displays

This is an array of objects that will be used for spawning in countdown displays when the game loads the track. Provided with the tools is a countdown display with the exact same dimensions as the ingame displays. This can be found in BallisticNGTools/Prefabs, drag the prefab into the scene to add a new one.

### Race Cameras

This is an array of objects that will be used for spawning in the race overview cameras you see dotted around the track. These act as both a visual extra and also serve as the cameras that track the ships on the results screen. To act as a visual representation of where they are, a prefab has been prepare that you can drag into the scene. Like the countdown display this can be found in BallisticNGTools/Prefabs.

### Culled Objects

BallisticNG uses an artifical clipping distance built into its shaders to emulate Playstation One hardware limitations. However this only applies to any objects that are using the specialized shaders, so objects such as particles and the countdown displays do not get automatically culled. To work around this the game has as culling manager that disables objects if they are outside of the artifical clipping distance.

### Mirror Objects

This is an array of transforms that will be flipped when mirror mode is activated. All you really need to include in this is the track and scene parent objects, unless you have any other objects which do not sit inside the scene parent itself. The game will automatically add generated countdown displays and race cameras to this list.

### How do I add stuff to these lists?

To add objects to these array lists all you need to do is drag the object you want into the name. This will add it to the array, when you have items in the array you can delete them by right clicking them and going to "Delete Array Elements". If you lock the inspector you can select multiple gameobjects and drag them into the array list.

## Animation Manager

The animation manager is an optimization to reduce Update and FixedUpdate hooks in Unity. For more technical details, see Scripted Track Animations

Any scripted animations should be added to this manager. Anything that extends from the base animation class will have two buttons in its inspector that can be used to automatically add them to the Update or FixedUpdate lists.

## Track Data

The Track Data object is what stores references to all of the track data in the scene, all of the internal workings are hidden and only the stuff you need is presented to you.

### Track Floor/Wall

These two object fields simply point to the Track Floor and Wall objects, these are required for generated track data.

### Generate Data

This button will generate the track data. If you used the Track Wizard then you do not need to click this button.

### Force Atlas Update

This button will regenerate the texture atlas and UVs for the track.

### Force Tile Update

This button will force all of the tiles to regenerated their colors. This is really only useful for seeing special tile colors after rebaking lighting.

## Materials

Provided with the tools are a set of shaders. These shaders are designed as placeholders which will be replaced when your track is loaded into the game. When creating a material, set the materials shader to anything in the BallisticNG category. If you you want to force a material type (or use billboard materials) then see below.

Double sided materials means that both sides of a mesh face are drawn, it's up to you to decide how to use these but it's reccomended you use double sided materials for the track mesh and single sided materials for scenery.

Illumination in materials is additive, meaning you want a black background with colors on for illumination maps.

### VertexLit Cutout / VertexLit Cutout (Double Sided)

An opaque material that can be clipped within a set alpha threshold.

### VertexLit Transparent / VertexLit Transparent (Double Sided)

A transparent material, transparent objects can be subject to incorrect render order problems due to the nature of BallisticNG using forward rendering. Keep this in mind before making environment decisions.

## Ballistic Material

Ballistic Material is a script that contains a dropdown of options for forcing a material type. This is not the suggested method of applying materials, but is required if you want to use the billboard material.

Attach this to any objects with a mesh renderer you wish to apply this too, you can attach it by going to Component -> BallisticNG -> Material on Unity's menu bar.

## Ballistic Mesh Collider

Ballistic Mesh Collider is a script that contains a dropdown of options for different collision types. Keep in mind that all collisions will be mesh colliders, as the name suggests. Due to the nature of BallisticNG's physics it is not reccomend you throw this on everything, only certain set pieces that should obviously be collidable.

### Track Floor

Attach this to your track floor and nothing else! This is used as a flag for the lightmapper to indicate this is a part of the track. If you use the Track Wizard then this has already been done for you.

### Scenery Floor

Attach this to any meshes you want players to be able to hover over. Keep in mind that the game will have to copy all of the mesh elements to work with for both hovering and rotation, this will only happen for every time you switch between the track floor and different scenery floors but it could cause hiccups on complex meshes!

### Track Wall

Attach this to your track wall and nothing else! This is used as a flag for the lightmapper to indicate this is a part of the track. If you use the Track Wizard then this has already been done for you.

### Scenery Wall

Attach this to any meshes you want players to collide with. This will make the mesh this is attached to behave like the tracck walls.

## Zone Disable

Attach this script to any objects you want to be disabled in zone mode. Attach this to your skydome and cross plane vegitation.

## Jump Zone

Jump zones are trigger volumes that push ships around and increase acceleration. If acceleration is set to zero then it will not affect a ships acceleration. These are just a script, attach them to any empty gameobject to set them up.

The idea of Jump zones is to allow you to create large jumps that ships can fly over by increasing their acceleration and pushing them at a constant speed. You can configure the push speed and acceleration per speed class. The acceleration is a multiplier.

There are two ways to scale a jumpzone, you can rather use the Zone Extents fields or just scale the object, you can also combine both of these if you want.

### Push Pitch/Yaw Offset

Pitch/Yaw rotation offsets, this is releative to the jumpzone objects rotation.

### Acceleration Amount

How much to multiply the ships acceleration by when inside the jump zone.

## Respawn Zone

Respawn Zones are trigger volumes that force the ship to respawn. Their use cases are for blocking off unintended track skips and getting the player back onto the track quickly if they go out of bounds. Note you do not need to surround your entire track in respawn zones, the game has a system in place that keeps track of where the player is in relation to the track and can respawn them automatically if need be.

To create a respawn zone, go to Component - BallisticNG - Respawn Zone on Unity's title bar with an object selected to attach the ModRespawnZone script. All you need to do now is position, rotate and scale it however you want. The volume of the zone is visualized.

## Skies

Skies in BallisticNG are handled through skydomes. You can actually use any mesh you want, it just has to be a mesh. You can apply any material to this mesh, however it is reccomended you use the builtin Unity shader called Unlit/Texture. Make sure your sky mesh has a lightmapping option script attached with it set to ignore lightmapping and both shadow options turned oiff.

Skies should be setup as a repeating flat texture, the provided skydomes are UVd to wrap the image spherically. You can find the provided skydomes in the Ballistic Assets/Skies folder.

## Render Targets

Render Targets allow you to use a camera to render what it can see onto a material. Render Targets are always rendered at 128x128. There are two components needed to make a render target work.

### Render Target Display

This is what updates a material, attach this to a mesh renderer. This will create an instance of the material in the mesh renderer. The render target display waits a frame until it configures the material, this gives it time for any material overrides to take place.

**Texture Names** - This is an array of the names of the texture in the shader to update. The default names for all BallisticNG materials are \_*MainTex* and *\_Illum*.

**Target Camera** - This is a reference to the Render Target Camera which will be used to render.

### Render Target Camera

This is what does the rendering. Attach this to an empty gameobject. The camera will be created automatically with all of the settings it needs.

**Framerate** - How fast the camera renders (FPS). The default value is 24, it's reccomended you keep this value low as it will save your performance.

**Field of View** - The field of the view for the camera. This is updated every time the camera renders so you can update it through a script if you want too.

**Use Main Camera** - Show the players display instead of creating an individual camera.

### Performance

Render targets should be used sparingly, especially if you use higher framerates. Cameras are only rendered at the set framerate. Every time the camera renders it has to copy the pixel data into a texture and upload the changes to the GPU, the impact of this is dampened by how small the texture is, but if you add loads of these up then you will quickly find yourself dropping frames very quickly. The memory footprint of this is also very small given the texture size, again though building them up will quickly increase the memory footprint.

## Reflection Probes

Reflection probes are a feature in Unity that allow you to bake or generate cubemap reflections at runtime from a given point. BallisticNG's ships use these when ship reflections are turned on.

If you want to setup reflection probes on your track, make sure you set the type to Realtime, refresh mode to On Awake and set the resolution to 64. This will generate the cubemap with a resolution of 64x64 when your custom track loads. You should see the reflection pop up inside the gizmo sphere that is placed where your reflection probe is.