Custom Suspension — Full Tutorial (Advanced Suspension Maker)

🐣 New to this? Read GETTING_STARTED.md first — it’s the simple, click-by-click version. This file is the deep reference (how it all works under the hood).

End-to-end guide to building a custom, articulated, per-car suspension for CarX Drift Online: study the basegame rig, author your own in the Kino content SDK, and have the mod drive it in-game.

Note (toolset trimmed). The active SDK tools are: KSusp Bone (+ custom Inspector), Build Rig Hierarchy, Attach Parts to Bones, Bake Suspension Descriptor. The Auto-Skin Suspension, Export Suspension Bundle, and Import Suspension Dump editor tools were removed (they belonged to the single-mesh / standalone-bundle / dump-study paths, which the current rigid-parts + chassis-embedded workflow doesn’t use). Sections below that mention them are kept for reference / git history. The in-game F9 dump and the mod’s dormant swap mode still exist; only the matching editor tools are gone.

0. The big picture — how the SDK half and the mod half align

There are two halves, and they connect through three shared artifacts (not through the SDK’s built-in part categories — see §9, there is no “Suspension” category):

  SDK / Unity (authoring + build)                 MOD / in-game (runtime)
  ───────────────────────────────                 ───────────────────────
  mesh + bone GameObjects                          GameBindings.GetWheelTransforms()
  + KSusp* components                              (reads car's live wheel data)
        │                                                   │
        │ bake                                              │
        ▼                                                   ▼
  ① <name>.suspension.json  ───────────────────▶  SuspensionAnimator (copy/aim/span)
        │ build                                             ▲
        ▼                                                   │ instantiates + drives
  ② <name>.bundle  ────────────────────────────▶  mod loads it + swaps stock suspension
        │                                                   │
        └──────── ③ bone NAME convention ───────────────────┘

The three contracts that keep the halves in sync:

So the mod never depends on the SDK directly — it depends on those three things. Change a bone name in Unity → re-bake ① so the names still match. That’s the whole alignment.

1. Where everything lives

Kino content SDK (Unity project): …\kino_content_sdk (wherever you unpacked the Kino content SDK) (HDRP project. Note: OneDrive may mark some files read-only; “always keep on this device”.)

Game: your Steam library, e.g. …\steamapps\common\CarX Drift Racing Online (Steam ▸ right-click CarX ▸ Manage ▸ Browse local files, if you’re not sure which drive.)

• KSL extensions: kino\extensions\ (the mod lives here as AdvancedSusp.kse)
• Dumps: kino\dumps\<timestamp>\
• Suggested custom-part drop: kino\suspensions\ (you create this)

This repo (mod source):

• src/Mod/ → builds the mod DLL → packed to AdvancedSusp.kse
• src/Editor/, src/Authoring/ → deploy into the SDK project (see §2)

Deploy the SDK-side tools into the SDK project

Copy these into the SDK Unity project:

After copying, Unity compiles them and you get a Tools ▸ KSL menu.

2. Prerequisites

• The SDK project opens in the same Unity + HDRP version as the game (AssetBundles are version-locked). Don’t upgrade it.
• The mod (AdvancedSusp.kse) is installed and loads (see this repo’s README.md).
• For the material: the basegame uses Shader Graphs/CarGeneric, which the SDK does not ship. Options:
  1. Author with an HDRP Lit (or an existing SDK car shader) now; have the mod re-assign Shader.Find("Shader Graphs/CarGeneric") at runtime (the game already has it loaded).
  2. Recreate a CarGeneric ShaderGraph with the same property names (_BaseMap/_PackMap/_NormalMap/_ColormaskMap/_BaseColor/_SecondaryColor/_ThirdColor). Either way the colormask (R/G/B of _ColormaskMap → Base/Secondary/Third colour) is what gives independently-recolourable zones.

3. Part 1 — Study the basegame suspension (mod side, already working)

1. Load into a car in-game.
2. Press F9 (or the menu button in the KSL panel) → a dump is written to kino\dumps\<timestamp>\targets\Mesh_Suspension\.
3. Study it:
   • Open geometry.glb in Blender (rig comes in posed/skinned), or
   • In the SDK: Tools ▸ KSL ▸ Import Suspension Dump → pick the dump folder → it rebuilds a prefab under Assets/KSL_DumpImports/ you can inspect.

The basegame rig (front MacPherson + rear multilink, 49 bones) is your reference for what a working rig looks like: Root → Front/Rear → FR/FL/RR/RL → {Lower_Arm, Upper_Arm, Lower_ShA, Upper_ShA, SteeringRod, Wheel}.

4. Part 2 — Author your suspension in the SDK

1. Create a folder, e.g. Assets/Content/CarParts/Examples/MySuspension/.
2. Bring in / model your suspension mesh (one SkinnedMeshRenderer, name it Mesh_Suspension to match the basegame convention).
3. Build a bone hierarchy of empty GameObjects as children under the mesh’s root. You need, per corner, the bones your design uses: a wheel-mount, control arms/links, a shock.
4. Assign the material (see §2). Paint the colormask so the zones you want recolourable map to R/G/B.

Per-car: because the mod loads and swaps the suspension itself (suspension isn’t a selectable category and the game hardcodes it — see §9), you make one bundle per car and place each corner at that car’s geometry. The mod still auto-fits width/wheelbase live (the wheel bones follow the car’s wheel transforms), so you mostly need the inboard/chassis points right for each car.

5. Part 3 — Annotate the bones (component-based, no JSON by hand)

In the Inspector, add the KSusp* components:

• KSuspensionRoot on the rig root — set suspensionType (label, e.g. “MacPherson”).
• KSuspCornerGroup on each corner node (FR/FL/RR/RL) — set corner. Everything beneath inherits that corner.
• KSuspWheelBone on the wheel-mount bone — it copies the car’s wheel transform (this is what gives track width + wheelbase + travel + steer automatically).
• KSuspAimBone on each control arm / link / steering rod — drag the target locator it should point at (usually a child of the wheel bone so it moves with the wheel). Set aimAxis = the bone’s local axis that should aim (default +Z).
• KSuspShock on each shock assembly (see below).

Hub rotation modes (front vs rear)

The Hub’s Wheel Rotation picks how much of the game wheel’s orientation the upright copies. It mirrors the wheel — it never generates motion the wheel doesn’t have:

SteerCamber on the rear — it will not steer left/right, because the game doesn’t steer the rear wheels, so there’s no steering input to copy. You still get camber + toe (static toe, plus dynamic toe / bump-steer through travel), which is exactly what a rear hub should do. SteerCamber doesn’t add fake steering — it only reflects what the real wheel does. So keep the rear on SteerCamber; the front swings because the front wheels are steered, the rear won’t.

Shocks (body + spring + tophat)

A coilover is three parts; put one KSuspShock on the assembly and wire:

The baker expands this into a rigid span (body) + a scaling span (spring). The tophat is “fixed based on its position in the car” simply by being authored there and left un-driven.

Grouping reference — what to put on each bone, per suspension type

Legend: ← Component means add that component; (child) means parent it under the line above so it inherits motion; (fixed) means a chassis bone with no component.

Diagrams (in docs/visuals/): MacPherson · double wishbone · multilink · cantilever.

Components unified. There is now ONE component — KSuspBone — with a Role dropdown. The trees below still show the old per-role component names; map them like this: KSuspWheelBone → Role Hub · KSuspAimBone → Role Arm · KSuspShock → Role Shock · KSuspWheelChild → Role RidesWithHub. KSuspCornerGroup is gone (corner is a dropdown on each KSuspBone). Marker names are free — just keep them unique.

MacPherson (strut rigid with the hub) — the strut rides and steers with the hub, so parent it under the wheel bone (no aim needed); only the spring compresses:

FR_Wheel                 ← KSuspWheelBone            (copy: travel + steer)
├── FR_StrutBody         (child, no component)       rides + steers with the hub
│   └── FR_LowerPerch    (child locator, no comp.)   spring lower seat (moves)
├── FR_LowerArm_End      (child locator, no comp.)   lower-arm aim target
└── FR_Steer_End         (child locator, no comp.)   steering aim target
FR_Tophat                (fixed)                      strut top mount
FR_StrutSpring           ← KSuspShock                tophat=FR_Tophat, lowerMount=FR_LowerPerch,
                                                      springBone=FR_StrutSpring, bodyBone=EMPTY
FR_LowerArm              ← KSuspAimBone              target = FR_LowerArm_End
FR_SteeringRod           ← KSuspAimBone              target = FR_Steer_End

Double wishbone — the shock mounts to an arm (not the hub), so the shock body aims (use bodyBone); arms aim at ball-joint locators under the upright:

XX_Upright               ← KSuspWheelBone            (copy)
├── XX_UpperBall         (child locator)             upper-arm aim target
├── XX_LowerBall         (child locator)             lower-arm aim target
XX_UpperArm              ← KSuspAimBone              target = XX_UpperBall
XX_LowerArm              ← KSuspAimBone              target = XX_LowerBall
│   └── XX_ShockLower    (child locator on lower arm) shock bottom mount
XX_Tophat                (fixed)                      shock top mount
XX_ShockBody             ← KSuspShock                tophat=XX_Tophat, lowerMount=XX_ShockLower,
                                                      bodyBone=XX_ShockBody, springBone=XX_Spring

Multilink — same as wishbone but N links, each its own aim:

RX_Upright               ← KSuspWheelBone            (copy)
├── RX_Link1_End … RX_LinkN_End   (child locators)   one aim target per link
RX_Link1 … RX_LinkN      ← KSuspAimBone (each)       target = its *_End locator
RX_Tophat                (fixed)
RX_ShockBody             ← KSuspShock                top=RX_Tophat, lowerMount on the lower link

Cantilever / pushrod — pushrod drives a rocker; the shock spans rocker→chassis:

XX_Upright               ← KSuspWheelBone            (copy)
│   └── XX_Pushrod_End   (child locator)             pushrod outboard target
XX_Rocker                (pivot bone)
│   ├── XX_Rocker_PushEnd  (child locator)           where the pushrod points
│   └── XX_Rocker_ShockEnd (child locator)           shock bottom mount
XX_Pushrod               ← KSuspAimBone              target = XX_Rocker_PushEnd
XX_Rocker                ← KSuspAimBone              target = XX_Pushrod_End  (rocker tracks the pushrod)
XX_ChassisShockMount     (fixed)
XX_ShockBody             ← KSuspShock                tophat=XX_ChassisShockMount,
                                                      lowerMount=XX_Rocker_ShockEnd, body+spring

Rule of thumb: rigid-with-hub parts get parented under the wheel bone; everything that pivots gets a KSuspAimBone; every spring gets a KSuspShock; chassis mounts stay fixed.

Deployment note (this build): the suspension is imported as part of the CustomChassis prefab of the KNPP part — i.e. it ships inside the chassis, built via the SDK’s CarParts Chassis category, not as a standalone .bundle. The custom chassis brings its own suspension mesh + bones, so the mod’s job is reduced to find the suspension bones on the loaded car + load the descriptor + animate (no bundle load / no stock swap needed; for a fully-custom chassis the game already skips loading the stock suspension). The descriptor (artifact ①) and bone-name contract (③) are unchanged. See §10.

6. Part 4 — Skin the mesh

The mesh must be a SkinnedMeshRenderer weighted to the bones so it deforms when they move. Two ways:

• Auto-skin (recommended): Tools ▸ KSL ▸ Auto-Skin Suspension → set Mesh object (the GameObject holding the mesh) and Bone root (your rig root) → Auto-Skin. It assigns each vertex to its nearest bone (rigid by default — perfect for mechanical parts), computes bindposes, saves a new mesh asset, and converts the object to a SkinnedMeshRenderer with bones + rootBone set. Turn on Blend seams only if you want soft top-2 blending at part boundaries. (Tip: place each bone inside the part it drives so “nearest bone” is unambiguous.)
• Manual: skin in your DCC / Unity, weighting each arm/spring/wheel section to its bone.

Then save the whole thing as a prefab.

7. Part 5 — Bake the descriptor (artifact ①)

Tools ▸ KSL ▸ Bake Suspension Descriptor → assign the rig root → Bake → saves <name>.suspension.json. The report warns about: missing corners, unresolved aim targets, a tophat accidentally under a wheel bone, and duplicate bone names (which would make the mod’s name lookup ambiguous — keep names unique).

Example baked corner (MacPherson FL):

{ "corner":"FL", "wheelBone":"FLWheel", "copyRotation":true,
  "aims":  [{ "bone":"FL_Lower_Arm", "target":"FL_Lower_Arm_1", "aimAxis":[0,0,1] }],
  "spans": [
    { "bone":"FL_ShockBody",   "top":"FL_LowerMount", "bottom":"FL_Tophat",     "scaleAxis":"z", "scale":false, "restLength":0 },
    { "bone":"FL_ShockSpring", "top":"FL_Tophat",     "bottom":"FL_LowerMount", "scaleAxis":"z", "scale":true,  "restLength":0 }
  ] }

8. Part 6 — Build the bundle (artifact ②)

Tools ▸ KSL ▸ Export Suspension Bundle → assign the prefab → Validate (fix errors) → Validate + Build → produces <name>.bundle.

Notes:

• It builds a raw AssetBundle (extension .bundle) containing exactly the one prefab — the game’s external loader instantiates GetAllAssetNames()[0].
• A CarSuspensionTarget component is not required — the mod animates the bones.

Chosen path — embed in the chassis: instead of a standalone .bundle, drop the suspension prefab (mesh + bones + KSusp* components) into your CustomChassis prefab and build it through the SDK’s CarParts ▸ Chassis tool → .knpp. The suspension then ships inside the chassis and installs like any chassis part. You still Bake the descriptor (artifact ①) and deploy it alongside; the mod reads it and animates the bones that came in with the chassis. (The Export Suspension Bundle tool stays as the standalone alternative.)

9. Part 7 — Deploy + per-car config

1. Put both artifacts where the mod can read them, e.g.: E:\...\CarX Drift Racing Online\kino\suspensions\ridge_gt\ridge.bundle E:\...\CarX Drift Racing Online\kino\suspensions\ridge_gt\ridge.suspension.json

2. Easiest (no config): the baker writes the carId (and a name) inside a custom-named .ksusp file. Drop any number of them in kino\suspensions\ — e.g. drift.ksusp, grip.ksusp. The mod scans them, keeps those whose carId matches RaceCar.carId, and when several share a carId it picks the one whose suspensionRoot bones resolve on the loaded chassis (so multiple setups per car don’t clash). A .ksusp may also carry a "bundle" field (relative to the file) for swap mode. The mod logs (carId N) for the current car.

   Or use kino\suspensions\config.json for explicit control (wins over the scan). Match by carId (precise) or car name (substring, either direction — Ridge_GT matches Ridge_GT(Clone)); point descriptor at a .ksusp:

   {
     "suspensions": [
       { "car": "Ridge_GT",
         "descriptor": "kino/suspensions/ridge_gt/ridge.suspension.json" },
   
       { "car": "SomeOtherCar",
         "bundle": "kino/suspensions/other/other.bundle",
         "descriptor": "kino/suspensions/other/other.suspension.json" }
     ]
   }
   

   The first entry (no bundle) is find + animate — for a suspension that ships inside the CustomChassis. The second (with bundle) is swap — a standalone bundle the mod loads and swaps in. In the KSL panel: Enable swap toggles the whole system; Reload config re-reads this file after edits.

Why the mod loads it itself (not a CarParts pack, not a path override): suspension is not customizable content in this game. The SDK CarParts categories are Wheel/Bumper/Skirt/…/Chassis/BrakeRotor/Tire — there is no Suspension. In CarVisualManager, any SuspensionId entry is removed from the visual-parts dictionary (line ~9697) and suspension is then loaded by hardcoded name: LoadPart(SuspensionId, flag2 ? null : "suspensionmacpherson") — "suspensionmacpherson" for stock cars, or null for a fully-custom car (whose own model carries its suspension). So there is no category and no path-override hook. The mod injects a custom suspension by loading the bundle itself and swapping the stock one at runtime (§10).

10. Part 8 — In-game (mod runtime)

This is built (SuspensionSwap, driven from the extension’s OnUpdate). Each ~0.5 s it checks the player car; when it changes it:

1. Finds the stock Mesh_Suspension SkinnedMeshRenderer and hides its renderer (bones stay, so the game’s own suspension targets don’t error).
2. AssetBundle.LoadFromFile(<bundle>) (reflective), loads the prefab, and instantiates it under the car’s Model at the stock suspension’s local transform.
3. Loads <name>.suspension.json → SuspensionAnimator.Load(...).
4. Every frame: animator.Tick(wheelTransforms) → wheel bones follow the wheel transforms (width/wheelbase/travel/steer), arms aim, shocks compress.

When the car changes (or swap is disabled) it restores the stock renderer and destroys the spawned suspension. (0Harmony is referenced if we ever prefer patching the suspension LoadPart instead of the runtime swap — but the swap keeps us off fragile game internals.)

Chassis-embedded mode (built): if the suspension ships inside the CustomChassis (the chosen path, §8), there’s nothing to load or swap — the bones are already on the car. SuspensionSwap picks the mode per config entry:

• entry has bundle → swap mode (hide stock, load bundle, instantiate, animate).
• entry has only descriptor (no bundle) → find + animate: the animator resolves the descriptor’s suspensionRoot + bones directly on the car and Ticks them. No load, no swap, no stock hide. So for your chassis-embedded suspension, just omit bundle in config.json.

Until that activation is wired, you can still author, bake, build, and validate everything.

11. Reference

Descriptor schema (artifact ①)

{
  "type": "MacPherson",            // label only
  "suspensionRoot": "Root",        // bone the mod searches under (FindDeep)
  "corners": [
    {
      "corner": "FL",              // FL | FR | RL | RR  → wheel index 0..3
      "wheelBone": "FLWheel",      // copies the wheel transform
      "rotation": "steercamber",   // steercamber (steer+camber, no spin) | steeronly (flat yaw) | full (+spin) | none
      "aims":  [ { "bone": "...", "target": "...", "aimAxis": [0,0,1] } ],
      "spans": [ { "bone": "...", "top": "...", "bottom": "...",
                   "scaleAxis": "z", "scale": true, "restLength": 0 } ]
    }
  ]
}

Primitives: copy (wheel bone ← wheel transform), aim (bone LookAt target), span (bone stretches top→bottom; scale:false = rigid). Any suspension type = a combination of these (MacPherson = 1 aim + 2 spans; double wishbone = 2 aims; multilink = N aims; cantilever = rocker aim + span).

Bone roles (component → primitive)

| Component | Primitive | Drives | |———–|———–|——–| | KSuspWheelBone | copy | wheel mount (width/wheelbase/travel/steer) | | KSuspAimBone | aim | control arms, links, steering rods, rockers | | KSuspShock | span ×2 | rigid body + compressing spring (tophat fixed) | | KSuspSpanBone | span | anything exotic / manual |

Suspension data the mod reads (per wheel, reflective via GameBindings)

• car.GetWheelTransform(WheelIndex) — positioned per car (track/wheelbase) and animated (travel in localPosition.y, steer in rotation). This is the single source.
• car.GetWheel(idx).topPos / .maxSpringLen — if you ever want normalized travel.

12. Status

Things to verify in-engine (can’t be tested outside the game)

• The runtime swap works: hiding the stock Mesh_Suspension and instantiating our bundle under Model loads + renders correctly.
• BakeMesh-recovered geometry / GLB orientation look correct.
• The bundle’s material renders (shader-reference / CarGeneric handling, §2).

13. Troubleshooting

• Mesh loads but doesn’t move → descriptor not loaded, or bone names in ① don’t match ② (contract ③). Re-bake after any rename.
• Suspension too wide/narrow → the wheel bones aren’t following; check KSuspWheelBone is on the right bone and the car exposes GetWheelTransform (logged by the mod).
• Spring doesn’t compress → KSuspShock.springBone axis wrong, or top/bottom swapped.
• Tophat moves with the wheel → it’s parented under the wheel bone; reparent to chassis.
• Mirrored / inside-out in Blender → GLB winding; tell me and I’ll flip it.
• Pink material in-game → shader reference didn’t resolve; use the runtime Shader.Find("Shader Graphs/CarGeneric") fix-up (§2).