ModsUnityAssetBundles

The Colonists Unity asset bundle naming convention AND hierarchy

Note Read/Write should be enabled in Unity Import Settings on imported models (on the model tab).
If it is not, the custom_log.txt will typically contain an error similar to
Not allowed to access vertices on mesh 'xxx' (isReadable is false; Read/Write must be enabled in import settings)

Unity Project Example Assets

Below is a Unity project with some common example assets for mods that can be downloaded and loaded into Unity.
Example Assets Unity Project

When you install this package, the Unity project will be in version 2020.3.37f1. It is best to stay in this this version and not upgrade to a newer version.

One method is to download the compressed file, uncompress it, then "OPEN" the project in the Unity Hub. You may get an error ("No 'git' executable was found") and you can ignore that error and continue.

Unity Package - Asset Bundle builder

A Unity Package to help build asset bundles for mods for The Colonists is available and can be found here, along with instructions:
Unity Package - Asset Bundle builder

One method is to download the compressed file, uncompress it, and install it using the instructions but follow the installation to "+ Add package from disk...".

The Unity Console should show an information message upon successful AB built for each. e.g. Asset Bundle built: My_test_AB.
The Asset Bundle Builder option "Clean Existing Asset Bundles" will delete every asset bundle in the target folder before building. Otherwise, only modified ABs will overwrite existing ABs.

3D Models & Colliders

It is recommended to have a collider (or two) in the 3D models to make the game play more user friendly. Without a collider then you can only select the 3D model by selecting the tile(s) it is occupying. While this may be easier to do from a top down play, any other view angle would make selecting the 3D model more challenging without a collider. See specific Asset page for information on colliders to include in assets:

1. Buildings: ModBuildings
2. Natural Resources: ModNatural_Resources
3. Resources: ModResources
4. Flora: ModFlora
5. Boats: ModBoats

Example of Building hierarchy showing the Collider (found in Unity Project Example Assets):

LOD (level of detail) and Culling

General guidelines for model size (by number of vertices) and when to use LOD to improve game performance can be surmised by comparing to the Chocolate Factory (a fairly detailed building) that has ~3,000 vertices.
A building that would occur infrequently like a monument with 15,000 vertices should not have performance issues, but a building with 10 instances at 15,000 vertices might.
Using a LOD with far fewer vertices for views far away from the building (zoomed out) would be a good compromise.
Objects that can have many instances in game (e.g. resources, flora, or animals) should limit vertices for better performance.
For comparison, L1 Energy model has 354 vertices when zoomed in (LOD 0) and drops to 158 vertices when zoomed out (LOD 1).

(LOD can be automated and range can be changed in unity)

TIP: If the correct naming convention and hierarchy are used in a 3d modelling program that exports an FBX file, the LOD group is automatically created when imported into Unity .

E.g. for

anyNameButNotNecessaryEmptyObject

xyz1_LOD0 (mesh object for LOD 0)

xyz1_LOD1 (mesh object for LOD 1)

the prefab "xyz1" will be created w/ the 2 LODs under it.

Decent settings for LOD %'s, with LOD bias at 0.5, for resources are

100%

←

LOD0

→

7%

←

LOD1

→

2%

←

LOD2

→

0%

←

culled

Other assets that appear less frequently might use

100%

←

LOD0

→

2%

←

LOD1

→

0%

←

culled

"closest", i.e. highest detail, is LOD0.

General Hierarchy

ASSETS

prefabs

Specific Hierarchies

ANIMALS

animal_200

BOATS

boat_200

Main (active state)

Construction (construction state)

ResourceHolder (location for resource storage) empty gameobject is best

UnitHolder (location for the captainbot to stand) empty gameobject is best

BUILDINGS

building_200

Construction_L1 (under construction building #200 for level 1)

Main_Burn (object for construction burn particle effects, fire, when territory lost for level 1)

Main_L1 (finished building #200 for level 1)

Main_Burn (object for main burn particle effects, fire, when territory lost for level 1)

Production (contains animated object for production for level 1)

Rubble_L1 (Rubble for when territory lost for level 1)

Rubble_Burn (object for rubble burn particle effects, smoke, when territory lost for level 1)

Construction_L2

Main_Burn

Main_L2

Main_Burn

Production

Rubble_L2

Rubble_Burn

Construction_L3

Main_Burn

Main_L3

Main_Burn

Production

Rubble_L3

Rubble_Burn

• Note any object ending with "_Burn" will have burn particles applied when the building burns. The Object can not be a Prefab, so be sure to unpack it.

FLORA

flora_200

Main (inclusion allows 360 random rotation)

NATURAL RESOURCES

naturalresources_200

subasset_naturalresources_200_0 (1st fifth of mineable resource)

subasset_naturalresources_200_1 (2nd fifth of mineable resource)

subasset_naturalresources_200_2 (3rd fifth of mineable resource)

subasset_naturalresources_200_3 (4th fifth of mineable resource)

subasset_naturalresources_200_4 (5th fifth of mineable resource)

PROJECTILES

projectile_200

RESOURCES

resource_200

STRUCTURES

subasset_treefieldtree_200

Main: (base tree)

Fruit (fruit object on tree when fully grown)

subasset_plantablefieldplantable_200

Main

Example Hierarchy

Example of Building hierarchy of assets and naming convention in Unity:

Animation

Also see Building Specific hierarchies.

BUILDING PRODUCTION ANIMATION

Animations can be added to the Production object. Create two animations for the object:

1. One will be must end with "Idle" (e.g. Building200_Production_Idle).
2. One will end with "ProcessLoop" or "ProcessOnce" (all though this is not necessary but will help keep things organized when following the example)

The "idle" Animation in Unity, is not active no matter whether you put animation actions in it or not: "idle" is basically just a reset point, it doesn't process it as an animation as the building is not considered to be "dirty" when idle.

The two process animations (wrap modes) are:

A) looped (name ends with "processloop", e.g. Building200_Production_ProcessLoop)

B) whole length (name ends with "processonce", e.g. Building200_Production_ProcessOnce)

Review the "activeDirtyType" setting as shown here: BuildingProductionDataInfo.

Note: Animations that plug into existing behaviours, like production buildings, will need to be marked legacy in Unity. (Unity Community How-to)

BUILDING PARTICLE EFFECTS

For particle effects (e.g. smoke, sparks, wood chips, etc) you can add 1 or more Particle Systems to the Production_Lx object, where "x" = the building level.

BURNING EFFECT

The "BURN" effect is built into the game. To activate it, there must be at least one object marked with the suffix "_Burn". See Building Specific hierarchies and notice that there are "_Burn" items under Construction, Main and Rubble. The "BURN" effect is activated when a building is no longer covered by a territory ownership building. This can happen from dismantling/destroying a Watchtower, Harbour, etc. or from losing such buildings in a combat scenario.

Example of Building animation in Unity:
(in this example the Particle Effect are sparks coming from the building and the Animation is the bouncing ball and can be found in Unity Project Example Assets )


Example of a Common Animation Issue: Smooth Rotation
Change both the start and end animation keyframes to match image below.

Example Step-by-Step Mods

These examples should help you with the general flow, showing only minimum requirements. See Example_Step-by-Step_Mods