Zimension Docs

Unity import troubleshooting

Resolve wrong ZIP selection, package setup, compilation and wiring issues, missing animations, oversized weapons, vehicle exit and unsupported features.

Native conversion · importer 0.3.11

The ZIP does not open as a Unity project

Extract the reusable ZimensionUnity-0.3.11.zip template first. In Unity Hub, click Projects > Add > Add project from disk. Choose the extracted ZimensionUnity folder and confirm with Select Folder or Open. Do not use New project for this template.

Check the selected folder directly contains Assets, Packages and ProjectSettings together. If you only see another ZimensionUnity folder, go one level deeper. If you are inside Assets, Packages or ProjectSettings, go one level up. An extraction tool may create a versioned ZimensionUnity-0.3.11 outer folder; that is not the project root.

Your project export ZIP is a different file. Keep it compressed, open the template in the Unity Editor, then choose Zimension > Import from Zimension > From a file > Zip…. Select your project ZIP, click Open, and click Import.

The import appears finished, but events do not run

Wait for Unity's C# compilation and the Console message Connected <Project>Logic in <scene>. The importer writes the script first and connects scene references after the assembly reload.

Resolve Console compile errors before testing gameplay. Check the generated logic component on Game and review export-report.json. An event must exist in the project's registered events to receive its generated bindings.

The character does not hold or animate the gun

Install the updated importer and reimport the project so the Player Animator is rebuilt. Confirm the export contains weapon animation libraries and the controller includes Idle_rifle_aim or Idle_pistol, firing states and reload states.

Check PlayerController.rightHand and weaponGripCorrection. Recognisable humanoid rigs use the source animation rig's corrected grip frame. Animation libraries may have skeletons without meshes; these are supported. If the rig cannot be mapped, the report describes the bone-bound fallback.

The gun is huge or its muzzle floats above the player

Reimport using the updated package so the model's authored prefab root scale/rotation and the baked colliders are regenerated. Weapon.keepWorldSize should be enabled.

The hand grip uses metre-based offsets independent of armature scale. Pickup stops placement animations from writing to the held transform. Check Weapon.holdPosition, holdEuler and its Muzzle child against your Zimension grip/fire-point adjustments. The saved gunFireTransform sets muzzle position and rotation; the camera selects the aim point.

Vehicle exit only moves the camera

Use F or E while driving. The updated controller clears the old interaction selection so the exit key cannot immediately enter the same vehicle again. Exit places the player beyond the vehicle bounds and restores the CharacterController.

Update the package if you still have the earlier controller, then reimport the project. If you replaced the vehicle controller, call Vehicle.Exit rather than only moving the camera or player Transform.

Teleport or checkpoint events do nothing

Use the updated importer and reimport the project. Confirm the scene's GameManager.spawnPoints has the expected entries, and check that the authored event is listed in the project events.

A spawn point's event activates the next respawn pose. teleportEvent moves the player immediately without changing the checkpoint. A point needs a valid saved transformation; invalid poses are skipped and reported.

Movement input is disabled

Run Zimension > Setup Project and check Unity's Active Input Handling supports the Input Manager (Both is used by project setup). Click inside the Game view after starting play to capture the cursor.

Check that the game is not paused, on the start/death screen, or explicitly frozen by a gameplay event.

A browser feature is missing

Check the native feature matrix and export-report.json. Custom HUDs, overlays and camera cutscenes have supported conversion paths, with limits; use the current template and reimport the project. For Meta Quest controller VR, use Enable VR and the XR setup instructions on the Unity workflow page. Advanced XR, multiplayer, objectives and other unsupported systems still need a Unity implementation.

For a useful bug report, include importer and Unity versions, reproduction steps, relevant Console errors and export-report.json. Share project exports only with people you intend to give access to the project's assets.

Zimension AI

Docs assistant

How can I help?

Ask anything about Zimension docs

AI may make mistakes. Always verify with official docs.