Spline Movement

Overview

Splines are used to move the player through the level. This template includes the Unity Splines package, which provides tools for creating and editing movement paths.

For more information on how to work with this package, see here.

Only one spline is used for player movement in a level. The spline is created during level design and registered in the Level component.

The logic responsible for moving the player along the spline is implemented in the SplineMover script. The PlayerContext component provides access to the SplineMover.

Player movement along the spline is handled by the PlayerRunState. When the player enters this state, the Update method calls playerContext.SplineMover.UpdatePosition() every frame to process movement along the spline.

A simplified diagram of class relationships in the context of spline motion:

PlayerStateMachine
        |
        v
 PlayerRunState
        |
        v
  IPlayerContext
        |
        v
  PlayerContext
        |
        +-------------------+
        |                   |
        v                   v
   SplineMover         PlayerStats
        |
        v
  Unity SplineContainer

SplineMover

The SplineMover component moves the player automatically along a predefined Unity Spline while dynamically controlling speed and orientation.

Key Features

• Movement along SplineContainer

• Smooth acceleration and deceleration

• Automatic rotation aligned with spline tangent

• Speed switching via trigger zones

• Completion callback when reaching the end of the spline

How It Works

• Movement is calculated in normalized spline space (0–1)

• Speed is interpolated using acceleration values from PlayerConfig

• Player position and rotation are updated using SplineUtility.Evaluate

• When the end of the spline is reached, the Completed event is fired

Trigger-Based Speed Control

When the player enters a trigger with the specified speedChangerTag:

• Movement speed switches between:

  • Start speed

  • Player’s current upgraded speed

• Camera can automatically switch to a finish view

• UI elements (such as health bar) can be hidden

For more details, click here.

Public API

• UpdatePosition() — advances the player along the spline

• SetPosition() — manually applies position and rotation

• Restart() — resets movement progress

• NormalizedTime — current movement progress (0–1)

Movement Progress

Schematic of Player Progress Along the Spline

[SplineMover]  <-- controls the player’s movement along the spline
      |
      |  NormalizedTime (0–1)
      v
[MovementTracker]  <-- calculates progress and traveled distance
      |
      |  Distance(), Progress
      v
[HUDView]  <-- displays player progress via MeterProgress
      |
      |  UpdateMeterProgress(MovementTracker tracker)
      v
[UI] Slider + Text (traveled distance)

The user interface displays a level progress indicator. This indicator reflects the player’s current position along the spline, showing real-time progress through the level.

To work with the progress indicator, pay attention to the following classes:

• MeterProgress

MeterProgress is a UI helper component that displays the player’s movement progress along the level. It updates a slider to visualize overall progress and shows the traveled distance in meters using a text label, providing clear real-time feedback during spline-based movement.

• HUDView

HUDView uses the MeterProgress component to visualize the player’s movement progress along the level. It controls the visibility of the progress meter, resets its value when the HUD is enabled, and updates both the traveled distance (in meters) and normalized progress based on data provided by a MovementTracker.

During gameplay, GameLoopState calls UpdateMeterProgress() every frame, making the HUD a passive view layer that reflects spline movement progress without containing any movement logic itself.

• MovementTracker

MovementTracker is a utility class that tracks an entity’s progress along a spline. It calculates the traveled distance in meters via the Distance() method and provides the normalized progress (0–1) through the Progress property, both based on the NormalizedTime of the entity’s SplineMover.

This class depends on IPlayerContext to access the active SplineMover and its associated SplineContainer, making it a read-only tracking layer that separates movement data from UI and gameplay logic.

How to Add a New Spline-Driven Entity

This template allows not only the player but also other objects to move along a spline. The following guide shows a simple example of how to set up an object to move along a spline after the level starts. When the object reaches the end of the spline, it will be destroyed.

Steps to Add a New Spline-Driven Object

1. Create the Entity GameObject Create a new GameObject in the scene representing your entity (for example, Helicopter). Add the following required components:

   • SplineMover — handles movement along the spline

   • Collider (if speed switching via trigger zones is needed)

   • Any visual or gameplay-specific components required for the object

2. Create a Script for the Entity Create a script (e.g., Helicopter.cs) that handles movement along the spline each frame and attach it to the GameObject:

using UnityEngine;
using Zenject;

namespace KrolStudio
{
    public class Helicopter : MonoBehaviour
    {
        [SerializeField] SplineMover splineMover;

        ILevelPlacer levelPlacer;

        [Inject]
        public void Construct(ILevelPlacer levelPlacer)
        {
            this.levelPlacer = levelPlacer;
        }

        void Start()
        {
            splineMover.spline = levelPlacer.GetPathSpline;
            splineMover.Restart();
            splineMover.SetPosition();
            splineMover.SetStartSpeed();

            splineMover.Completed += Finish;
        }

        void Update()
        {
            splineMover.UpdatePosition();
        }

        public void Finish()
        {
            Destroy(gameObject);
        }

        private void OnDestroy()
        {
            splineMover.Completed -= Finish;
        }
    }
}

1. Setup Zenject Dependency Injection The Helicopter component requests the LevelPlacer dependency via Zenject, so you need to add a ZenAutoInjecter component to the object. This informs Zenject from which container to inject the reference.

   ZenAutoInjecter is necessary because the level is created after the SceneContext initialization in the Level scene.

If the object were placed directly in the Level scene from the start, Zenject would automatically detect the Helicopter component during container initialization and inject the LevelPlacer reference.

Result

When the level starts, the Helicopter will begin moving along the spline. Once it reaches the end, it will be destroyed. This example can serve as a starting point or reference for implementing more advanced behaviors for spline-driven entities.