Import Ship Tutorial

From BallisticNG Wiki
Jump to: navigation, search

Arrow welcome

Welcome to the offical tutorial for importing your own ships into BallisticNG! Before you begin make sure you have installed a copy of the Unity editor, information on where you can find it and which version you need can be found on the Ballistic Unity Tools home page.

This tutorial will walk you through the processes of setting up your own ships and then show some of the more advanced features and freedoms available to you when building your ships. Remember that on top of this tutorial you can also find an example setup of the game's Precision Delta inside of the Unity Tools asset folders!

Before you begin reading, this tutorial assumes you have at least some experience with the Unity interface. If you don't have any experience then you can see the offical Unity documentation here:

Arrow a quick overview

Custom ships are prefabs made inside of Unity scenes and exported to .csf files. Unlike the previously used .shp format, these are compiled Unity assets and cannot be modified by other people once exported. Your source ship files are the unity scenes that you save them in, it's important you keep your scene files safe for this reason! If you like to keep yourself organized you can store multiple ships per scene and export them individually from that same scene.

Ships are split into two seperate prefab assets: ingame and frontend ships. The ingame ship is what's spawned in-game, everything in this prefab will be loaded into the game so that means anything you setup in addition to the required assets will also be included. While this means you get some freedom with adding extra stuff to your ship, we don't reccomended you go too overboard with intensive effects like particles for the sake of keeping the game playable for people on older hardware. The frontend ship is the asset that's loaded when the ship needs to be displayed on the menu, that's pretty much it.

Finally .csf files can be re-exported as you're playing the game! Frontend data will not be updated as that information is cached for your current play session, but the in-game prefab will update when you restart the event that you're currently playing. This can be useful for prototyping physic stats.

Arrow importing legacy .shp files

If you're only looking to import legacy .shp files then this first section is for you. NOTE: if the .shp file is tied to the Steam Workshop then you can only import the file if you published it. Make sure you're signed into Steam when importing your files for it to verify that you are the owner.

On the toolbar navigate to BallisticNG -> Ships -> Import From .SHP File and then select a valid v2 .shp file (a ship file exported with the current in-game ship importer). This will import the ships assets into your Unity project and configure the ship prefab in the active scene. Once the ship is imported you will want to make any adjustments, especially with the frontend mesh scale, and save the scene to save your ship. All workshop data is preserved so you can start uploading the ship to update your existing ship on the workshop.

Arrow asset requirements

BallisticNG itself is built with low-poly assets with a single material in mind. This is a restriction that you need to keep in mind when developing your custom ships. Make sure that you meet the following requirements:

  • Your ship is a single mesh (sub-meshes are fine) and is under 65,535 vertices, Unity's hard limit for vertices per mesh. Airbrake meshes are excluded from this and need to be their own meshes.
  • Your ship only has a single material, this material also needs to be shared across airbrake meshes.
  • Cockpit meshes should occupy the real space of your ships cockpit for VR players. The pivot of the cockpit is where the camera will be placed so make sure you line this up in your modeling software before exporting. Cockpit meshes should also use their own material.
  • There should be two versions of your cockpit: one with and one without the canopy (the glass and its supporting structures).
  • If showing the ships exterior from inside the cockpit it must be part of the cockpit mesh and must use the external ship meshes material (so you'll have 2 materials, one for the cockpit interior and the material for your ships exterior).
  • If using seperate airbrake meshes for animation you need a second version of your ship mesh with the airbrake meshes included. This is for the frontend mesh which is mentioned later on in the tutorial.
  • Seperated airbrakes should have pivots setup. The pivot should sit at the point the airbrake is going to rotate around and should be orientated so an axis is pointing along the airbrakes back edge (y axis facing down the edge with the z axis facing away from the airbrakes top surface is reccomended).
  • The ships pivot should be somewhere in the center of the mesh, this is important for ship shadow generation and will be explained later on in the tutorial.

The exterior in-game and frontend ship meshes are required assets, cockpits are not!

Arrow ingame asset spec

If you want to build ships that are to the same spec as the game's vanilla ones then here is the small list of them for you:

  • Meshes are typically 150-250 tris. No hard set limit was established for this but ship meshes try to stick around this range.
  • Exterior texture maps are 512x512, cockpit interior texture maps are 1024x1024.
  • All ships have a diffuse map, illumination map and reflection mask map.

Arrow asset importing

Import your assets into Unity like you would any other asset.

  • For meshes favour FBX or DAE over other formats like OBJ. OBJ doesn't store transform data and as such airbrake pivots will be lost so it's strongly reccomended you avoid OBJ.
  • For textures you can use any format you like, PNG and TGA are the typically the most used though.
  • Once you've imported your textures, click on your textures in the project view and in the inspector untick Generate Mip Maps, set Filter Mode to Point (no filtering) and click apply.
  • If your ship scale is off by multiples of 10 then it's reccomended you set the import scale factor first instead of scaling them in your ship prefab. To do this click on your meshes in the project view and in the inspector update the Scale Factor setting, then click apply.

Arrow ingame ship prefab setup

Before you begin this section you will want to be familar with scenes in Unity and how everything is structured. You will want to know the hiearchy tab, inspector tab, project tab, scene tab and have an understanding of gameobjects and gameobject hiearchies.

Arrow create the prefab

To create a new ship prefab navigate to the titlebar and then navigate to BallisticNG -> Ships -> Create New Ship. Once the prefab is created you will see a new default engine, vapor trail locations, navigation light locations and camera location notes.

In the hiearchy tab click on the object called Ingame Ship, in the inspector you will now see the main interface where you can configure everything. From this point on the tutorial will refer to this specific inspector as the ship inspector, when reading about this inspector you want to make sure you have the Ingame Ship object selected.


Arrow scale helpers

Scale helpers are ghost overlays of the vanilla ships, these are useful for scaling your own ships to the games. To activate them first make sure the ship inspector is open, change the Scaler Helper References option under the Editor Settings heading and click the Update Scaler Helpelr button to apply the changes. You may need to interact with the scene view to force it to refresh with the updated scale reference. ShipToolsScaleReference.jpg

Arrow exterior mesh setup

Once your ship is inside of Unity it's easy to get it setup in your prefab. In the project view navigate to the folder where your ship mesh is located and drag the mesh onto the Ingame Ship game object. This will spawn a copy of the ship as a child to the ship prefab. Once the ship is in you might want to adjust its position and scale, especially if you're using a scale helper.

Once your mesh has been added, navigate to the ship inspector and open the Edit Visuals foldout. You will see a field called External Mesh. Drag your ships external mesh object from the hiearchy view into this field. This is important so the game knows which mesh is your ships exterior, you won't be able to export your ship without first setting this up.

When setting up your ships transform do not move any parent objects as this will interfere with the ships shadow generation. To use the image to the right as an example, it is okay to scale Precision_Airbrakes but if you want to move the ship you would want to select Airbrake_Left, Airbrake_Right and PrecisionDelta_Body and move those instead. Another solution would be to use Precision_Airbrakes to setup the position and scale but then drop all of the meshes that are a child of it out so they're children of Ingame_Ship instead. When doing this Unity re-calculates the transforms so your position and scale will be retained relative to the new parent, take a look at the Precision Delta example scene for this approach in practice.



Arrow cockpit mesh setup

IMPORTANT: Once your cockpit meshes are setup disable their gameobjects so they arn't enabled when they're spawned into the game. With any number of objects selected, click the tick box to to the left of the object name field in the inspector to toggle it's enabled state.

Setting up your cockpit meshes is identical to setting up the exterior mesh. Before setting up your cockpit meshes it's reccomended you get the scale you want for the ship figured out first, you don't need to include cockpits in your exported ship so you can skip this stage for now and come back if you want.

Select both your canopy and non canopy meshes and drag them onto the Ingame Ship object to make them a child of it. Now select both objects in the heiarchy view and position/scale them so the cockpit matches up with the cockpit on your external mesh. If you want to ensure VR players can get the best experience out of your ship it is strongly reccomended that you match up the scale and position as closely as possiblle.

Now like with the external mesh, open up the ship inspector and expand the Edit Visuals foldout. You'll see two fields in here, one for the cockpit with the canopy and one for it without. Drag the appropiate meshes into these fields. If you only have 1 cockpit mesh, drag it into both fields.

Material ID setup
If your cockpit has the exterior ship mesh included you'll first off want to make sure that the exterior mesh is using the exterior meshes material, this is important for updating liveries for when you're inside the cockpit view. To do this first select one of your cockpits and look at the materials list in the Mesh Renderer component, you might need to expand the materials foldout. See which material is your exterior meshes material, if the material assigned for the exterior mesh is not correct then update it so it's the right one. Next to the material you will see Element # where # is a number. Make a note of this number as you'll need it for the next step.

Head back over to the ship inspector and expand the Edit Visuals foldout again. Under the two canopy fields you will see a field called Cockpit External Material Index. By default it's -1 which means the game will not attempt a livery update on anything. Update this value to the number you made a note of.




Arrow materials setup

Inside of the folder where you've placed your ship assets will be a sub-folder called Materials. This contains any imported materials from your ship and if you've maintained file names will also have the diffuse texture automatically added for you. By default this will be using Unity's standard shader and won't have any of the other maps setup so the materials must be configured manuallly.

Ships Exteriors
First select your material in the project view and in the inspector click the Shader dropdown and select the BallisticNG -> CustomShip or BallisticNG -> CustomShipCull shader, depending on your preference. Select your material from the project view and in the inspector drag your maps into the appropriate Reflection and Illumination slots. If the diffuse hasn't been automatically setup then drag over your diffuse map too.

Your ships material should be configured to reflect the default livery. Liveries are applied by updating the texture maps on this material.

For cockpits set the shader to BallisticNG -> VertexLit Transparent, this is the transparent shader that the vanilla cockpits use.


Arrow airbrakes setup

NOTE: There are no airbrake count restrictions, you can add as many as you like!

IMPORTANT: Make sure your airbrakes are using the same material as the exterior mesh, this is important for assigning liveries!

Before you begin configuring your airbrakes you must first make sure that your airbrakes pivots are setup. This must be done inside of your modeling software, each software has its own way of handling this so you'll need to use your softwares method of setting this up.

Take the image to the right as an example, the pivot is setup along the back edge of the airbrake with the Y axis pointing down it. The axis that's pointing down the edge of the airbrake is important as it will determine how you setup the rotation axis. As the Precision Deltas airbrake pivot has the Y axis ponting down the edge, this means we will be rotating our airbrake along the Y axis.

Create the airbrake definition
To create the airbrake definition head over to the ship inspector, expand the Edit Airbrakes foldout and click the green Add Airbrake button. Under the Target Components header drag your airbrake gameobject into the Airbrake Renderer and Airbrake Transform fields.

Configure the airbrake
You can now configure the airbrake using the available settings under the Target Components section. You might need to invert the rotation axis for the left airbrake, to do this you set the axis it's rotating along to -1 or you can use the Quick Axis Assign button to set this up.

Option Description
Input Response This determines what the airbrake responds to. Steering currently only works for player ships.
Airbrake Side The side of the ship this airbrake is on. This determines which input the airbrake responds to.
Up Angle The angle that the airbrake will raise to when extended.
Invert on left/right airbrake? Whether this airbrake should invert its angle when the airbrake for the oposite side is used. Ticking this willl give you the option to set the angle that the airbrake will lower to.
Rotation Axis The axis relative to the airbrakes pivot rotation that the airbrake will rotate along. Either set a single component to -1, 1 or use the Quick Axis Assign button to select the axis from a dropdown.
Up Speed How quickly the airbrake raises (normal)/lowers (inverted).
Down Speed How quickly the airbrake restores to its resting rotation.


Arrow locations setup

Locations are offsets on your ship defined by gameobjects that are children of the ship prefab. To setup these locations you just need to move the gameobjects in the scene. Hold down V and you can vertex snap gameobjects as you move them.

To access locations navigate to the ship inspector and expand the Edit Locations foldout.

Vapor Trail locations are required, navigation lights are not and you can safely delete the gameobjects.

Vapor trails locations are used to tell the game where the ships most outer wing tips are, these should be placed on the part of the ship that extends out the furthest. Navigation lights are red (left) and green (right) lights that flash in an alternating pattern, ideally you'd place these on your ships wing tips alongside the vapor trail locations.

The camera location fields allow you to adjust the offset of the external and internal cameras. The cockpit cameras position is defined by the cockpit meshes pivot. You can preview your chase camera offset by clicking the Preview Chase Camera (game tab) button and switching to the game view.

Scene View Gizmos Inside the scene view you will see some sphere gizmos with abbreviated labels, these are what each label stands for:

Abbreviation Full Name
LV Left Vapor Trail
RV Right Vapor Trail
LN Left Navigation Light
RN Right Navigation Light
EC External Camera
IC Internal Camera

Arrow engines setup

NOTE: There is no limit to how many engines you can setup!

NOTE: The engines color will always be white in the editor unless you manually edit the material. Colors you setup for your engine will be applied in-game only.

When you create a new ship you will be given a default engine to work with. An engine is a flare and trail that you add to your ships. You do not need both a flare and trail, if you only want a flare or only want a trail then you can safely delete the trail/flares gameobject and the game will simply not include it when loading your custom ship.

Adding Engines
To add a engine open the ship inspector and expand the Edit Engines foldout. Click the green Add Engine button to add a new engine. You will need to edit the engine by selecting the gameobjects in the hiearchy tab and moving them manually. You can select multiple engines to move, rotate and scale both the flare and trail at the same time.

If you only want either the trail or flare then all you need to do is delete the gameobject.

Deleting Engines
To delete an engine click the red X button on the header of the engine you want to delete. The gameobjects will be automatically deleted for you.

Customizing Engines
To set the color of your engine open the ship inspector and expand the Edit Visuals foldout. The first two options you will see are Engine Bright Color and Engine Dim Color. Click on the color to open up the color picker. The engine color is animated using the Dim and Bright colors, this allows you to add a faint flicker or color shift to the engines color. The animation uses a sine wave over time to calculate the blend factor.

You can also add your own textures to the engine components. To do this you will want to create a new material and use that material on the flare/trail instead. For the trail use the Particles -> Additive shader and for the flare use the BallisticNG -> Ships -> Player Flare shader. The player flare shader is only used when the player is controlling the ship, the game automatically swaps out the shader to an AI flare shader.

To apply the custom materials select the flare/trail gameobjects, expand the Materials foldout in the Mesh Renderer component and drop the material into the material slot.

Further Customization (1.1.5+)

Option Description
Reference Name The name of the engine. This can be used by code mods to flag out specific engines to do something with. For example the mini turbo exhausts with the INTERNAL_DRAG custom ship module.
Always Use Player Trail The engine will always use the player trail. Useful for creating flame based engine effects.
Ai Trail Width Curve Controls the width of the AI trail over it's length. Leave this empty with no key frames to use the game's default curve.
Use Engine Colors Controls whether the game should automatically apply the engine color from the prefab. Disable this if you have a code mod that handles the colors instead. For example the INTERNAL_DRAG custom ship module.
No Fire On Weapon Impact Controls whether the engine will emit fire particles when the ship is hit by a projectile.
Afterburner Boosts Intensity Controls whether using the afterburner will boost the engine colors intensity when used.
Turbo Boosts Intensity Controls whether using the turbo pickup will boost the engine colors intensity when used.
Pads Boosts Intensity Controls whether flying over speed pads (both tille and 3D variants) will boost the engine colors intensity.
Flare/Trail Alpha Range Controls the minimum and maximum alphas that the flare/trail components can have.
Flutter Toggles scale fluttering. This rapidly flucuates the trails size along the Flutter Scale axis when enabled.
Flutter Power Amount/Speed Curves Controls how the engine power affects the fluttering amount and speed
Flutter Speed Controls the base flutter speed.
Flutter Scale The axis and amount along that axis that the flutter scaling will affect. If you've configured your trail so Z is forward, you'd enter your flutter scale value in the Z field.
Scale With Speed Controls whether the trail will scale with the ships speed.
Scale Speed The axis and amount along that axis that the trail will scale with speed.
Scale With Engine Power Controls whether t he trail will scale with the ships engine power.
Engine Power Scalle The axis and amount along that axis that the trail will scale with the engine power.
Uv Scroll Speed How fast the trail UVs will scroll on each axis.


Arrow liveries setup

NOTE: Not all texture maps are required for each livery. At the very least you must have the diffuse map though.

Liveries are alternative textures for ships that can be selected on the menu, the AI will also use alternative liveries where possible too. An empty livery called Default is created for every new ship. Make sure you setup your maps for the default livery!

Managing Liveries
To create a new livery for your ship open the ship inspector and expand the Edit Liveries foldout. The new livery will be created and added to the list. Use the Livery Name field to set the menus display name of the livery and then set your texture maps below. Liveries only support the game's ship shader.

To delete a livery just click the red X button to the right of the liveries header.


Arrow physics stats setup

Physics stats is where you configure how your ship handles. To access these settings open the ship inspector and expand the Edit Stats foldout. Keep in mind that you can quickly prototype different settings in-game but leaving the game running in the background, exporting your ship and restarting the race to reload the ship file.

Prefab Stats
The editor comes with all of the in-game ships stats built in. Under the foldouts for entering your own stats you will find a section called Update To Prefab Stats. Select a ship from the dropdown and then click Apply Stats to update all of the stats on your ship.

Stat Setup

Setting Description
Max Speed How much force the engine will apply to the ship. This is not the top speed in a measurable distance per hour and is the actual force being applied to the ship.
Acceleration How fast the engine will accelerate the ship.
Engine Power Gain/Falloff In BNG engines have a throttle which you increase/decrease by holding/releasing the thrust input. This controls how fast the throttle increases/decreases.
Steer Speed How fast the ship can rotate per second in radians.
Steer Gain How fast the ship reaches its maximum steering speed.
Steer Falloff How fast the ship stops steering.
Steer Slide How much of a drift steering induces.
Tilt Angle How much the ship will tilt in response to steering.
Airbrake Turn How fast the airbrakes will rotate the ship per second in radians (scales with speed).
Airbrake Gain How fast the ship will reach its maximum airbrake turn speed.
Airbrake Falloff How fast the ship will stop rotating when the airbrakes are releases.
Gravity Airbourne Force How strong gravity is when the ship is airbourne
Gravity Grounded Force How strong gravity is when the ship is hovering (grounded).
Ship Weight How quickly the ship transitions from the grounded to airbourne gravity force when leaving the track.
Hover Height How far away from the ground the ship will hover.
Hover Force How much force to apply to the ship to make it hover.
Hover Damp How much to dampen the spring simulating the ships hover.
Rebound Bounce Power How much bottoming out rebounds the ship off the track floor.
Rebound Height Offset How far away from the ground the ship can be before making an impact is concidered.
Rebound Pitch Mod How much pitching the ship affects how easily the ship bottoms out.
Landing Rotation Power How much landing into the ships hover state causes the ship to pitch its nose up.
Bottom Out Rotation Power How much bottoming out causes the ship to pitch its nose up.
Rebound Bounce Power How fast the above 2 options pitches the ships nose.
Track Allignment Speed How fast the ship alligns itself to the track surface.
Pitch Angle The maximum angle in degrees that the ship can pitch relative to the tracks surface.
Pitch Speed How fast pitching responds to the players input.
Dive Speed How fast the ships nose dives down as the ship leaves the track.
Hover Rotation Power How much the ships nose pitches from its own hover force.
Hover Rotation Speed How fast the ships pitches in resonse to its own hover force.
Hover Rotation Threshold How resistant the ship is to its own hover force affect its pitch.
Grip How little the ship drifts.
Airbrake Drift Power How much of a drift the airbrakes induce when in use.
Airbrake Drift Gain How fast the airbrakes start the ships drift.
Airbrake Drift Falloff How fast the ship recovers from a drift when releasing the airbrakes.
Weapon Effectiveness How damaging this ships weapons are to other ships. This is a multiplier with 1 meaning this ship deals a weapons base damage to other ships.
Shielding Effectivness A multiplier for how much damage ships take. A value of 1 means this ship will take the full ammount of damage being dealt and a value of 0 means this ship will take no damage.

Arrow engine sound

To apply an engine sound to your ship first import the audio file you want to include, you should make sure it's a .wav or .ogg file. Next open the ship importer and drag your sounds asset onto the Engine Sound field or click the circle icon next to it and select your audio asset from the object browser window.


Arrow custom modules

Ships in BallisticNG are handled through a system that seperates behaviours into different modules that are executed in an explicit order and can intercommunicate with each other. Custom modules allows code mods to add their own behaviour modules into the game that custom ships can then reference.

Built-in Modules

Version Introduced Name Description
1.1.5 INTERNAL_DRAG Manages the engine colors (orange when no power, white when at max power, blue when boosting) and manages mini turbo exhausts for any engine with a reference name of turbo.
1.1.5 INTERNAL_TEMPEST Same as INTERNAL_DRAG but also plays the flameboost sound when hitting speed pads in 2159/floor hugger.

Once you have a custom module programmed in a code mod (or you've downloaded one) you reference the name that the module registers into the game and use the Custom Ship Module field in the ship inspector to tell the game which module to load. If the module doesn't exist or the name isn't correct the game won't load anything.

Keep in mind that for this system to work you will need to install and active code mods. If you're programming your own code mod for this feature it's strongly reccomended that you distribute your c# source files instead of libraries so others can inspect your code.

Arrow frontend ship prefab setup

The frontend is the main menu and any other menus where you will be able to select your ship. It is important that you configure these so players know a little bit about your ship before selecting it.

Setting up your frontend mesh is identical to setting up your in-game ship, instead this time you want to drag your frontend mesh onto the Frontend Ship object. Once you've dragged the ship in you'll want to set the position, rotation and scale to match the in-game ship but multiply the scale by 10. Unity supports math functions in text fields so you can you can do the multiplication by adding *10 to the end of your scale values. Right clicking the transform component header will also let you copy and paste transforms to and from different objects, this can be useful for very quickly getting your frontend ship configured.

For your own convenience you might also want to disable the frontend mesh's object to hide it.

Once the frontend ship is in your scene and scaled properly you will now also want to setup the reference to it so the game can read it. Open the ship inspector and expand the Edit Frontend Data foldout. Now drag your frontend ship object onto the Frontend Mesh field.

Finally you can configure your display name, display decription and out of 10 stats which will be shown on the menu.



Arrow save the scene, export to the game

To save your ship all you need to do is save your Unity scene. If you're uploading to the workshop then keep this scene safe as it contains your ships workshop ID which is required to upload the ship to the same workshop page later in the future.

To export your ship open the ship inspector and click the green Export Ship button and save the file to your MyShips folder (%INSTALL PATH%/UserData/MyShips). Create sub-folders in your MyShips foldler if you want to categorize your ships on the menu.

Arrow upload to the steam workshop

IMPORTANT: To upload your ship to the Steam workshop first make sure you have opened Unity after launching Steam.

Open the ship inspector and expand the Show Workshop Settings foldout. In here you need to enter your title, description, add tags, set a visibility type and add a preview image. Preview images can only be a JPG and are not allowed to be any larger then 1mb.

After you have setup your workshop details save your scene and then click the Upload To Workshop button. Once the upload has completed it's very important to save the scene again to store your workshop ID.

When uploading you can view the progress in the same area where you setup your workshop details, while uploading you will see a progress description and percentage value instead of the settings. Steam does not return the upload progress so it's not possible to provide an accurate upload progress bar, you will need to wait.