Agamotto

Time Manipulation & Simulation Tool for Unity

Open Source Agamotto v1.5.0 Unity 2019.4 - 2022+
Get on Asset Store Bitbucket Repository Changelog API Docs

What is it?

Agamotto is a time manipulation and simulation tool for Unity. It allows you to record objects' states in the past or simulate their physical and logical trajectories into the future, enabling smooth timeline scrubbing, rewinding, and trajectory forecasting.

Agamotto supports both deterministic physics simulations and code-driven simulations, complete with non-allocating timeline storage, trajectory renderers, and onion skinning tools.

Clarification: Agamotto is a timeline recording and simulation system rather than a real-time bullet-time slowdown tool. To scrub or replay time, an entity's trajectory must first be recorded in the past or pre-simulated into the future.

Video Walkthroughs

Presentation Overview

Feature & Demo Walkthrough

Quick Start

  1. Add a TimeStone: Add a TimeStone component to an empty GameObject in your scene.
  2. Enable Recording: In the TimeStone Inspector, check Record on start.
  3. Add TimeAgents: Attach a TimeAgent component to every GameObject you wish to record or simulate (e.g. falling spheres, physics props, characters).
  4. Initialize Agent List: Configure your TimeStone to target these agents (manually, by Tag, or by Layer).
  5. Hit Play: Press Play in the editor. Use the TimeStone runtime controller to pause, rewind, scrub, and inspect positions across the timeline.
Agamotto Quick Start GIF

Unity Compatibility

  • Unity 2020.1+ / 2021 LTS / 2022 LTS — Fully Tested & Supported
  • Unity 2019.4 LTS — Minimum Supported Version
  • Unity 2018 and older — Unsupported

Core Components

`TimeStone`

The orchestrator and central controller of Agamotto. It is responsible for:

  • Persisting continuous frame data for all tracked TimeAgents.
  • Executing physics and code-driven forward simulations.
  • Managing playback cursors (playbackTickCursor and addTickCursor).
Simulations & Clones: When running forward simulations, the TimeStone instantiates clones of tracked agents in a private physics scene, runs manual physics steps, and invokes simulation callbacks before returning the result.

`TimeAgent`

Attached to GameObjects that participate in time manipulation. Tracks transform positions, rotations, velocities, and custom user data over time.

Visualizers: `PathVisualizer` & `OnionSkinVisualizer`

  • PathVisualizer: Uses Unity's LineRenderer with tolerance-based vertex simplification to draw smooth predictive paths and trajectories.
  • OnionSkinVisualizer: Renders ghosted duplicate meshes across past and future timeline ticks for visual pose inspection and trajectory debugging.

Included Demo Projects

Agamotto includes multiple complete example scenes showcasing different use cases:

Physics Prediction (Pool Demo)

Pool Demo

Interactive trajectory forecasting for bounces, collisions, and cue shots.

Interactive Sorcerer (FPS Demo)

Sorcerer Demo

Grab, freeze, simulate, and rewind physical objects from a first-person perspective.

Code & Agent Simulation

Custom Agent Demo

Simulate character AI, waypoint navigation, and non-physics logic.

Tower Defense (Object Pooling)

Tower Defense Demo

Demonstrates object pooling for spawned projectiles and despawned enemies during timeline scrubs.

C# Script API & Code Samples

1. Starting and Stopping Recording

using UnityEngine;
using Agamotto;

public class RecordController : MonoBehaviour
{
    [SerializeField] private TimeStone _stone;

    public void OnStartRecordClicked()
    {
        _stone.StartRecording();
    }

    public void OnStopRecordClicked()
    {
        _stone.StopRecording();
    }
}

2. Running Forward Trajectory Simulation

// Trigger a forward physics & code simulation for 60 ticks (e.g. 1 second at 60fps)
_stone.simulationTicksDuration = 60;
_stone.StartSimulation(resetTimeline: true);

// Listen to completion event
_stone.onSimulationComplete.AddListener(() => {
    Debug.Log("Simulation completed! Trajectory updated.");
});

3. Timeline Playback & Rewind

// Set playback position to a specific tick
_stone.playbackTickCursor = targetTick;

// Play backwards (rewind)
_stone.playbackSpeed = -1.0f;
_stone.Play();

FAQ & Best Practices

How should I handle object destruction when rewinding?
Agamotto cannot re-instantiate GameObjects destroyed with Destroy(). If objects are spawned and despawned during timeline recording or simulation, you must use an object pool (as demonstrated in the Tower Defense demo).
Why must I not use Time.deltaTime in simulation code?
Forward simulation runs ahead of real time, often calculating many frames within a single Unity frame. Relying on Time.deltaTime will cause incorrect or inconsistent results. Always use the deltaTime passed as an argument in your simulation callbacks.
How do I avoid duplicate scripts during Onion Skinning?
Use the duplicatePrefab property on OnionSkinVisualizer to specify a simplified visual-only mesh prefab without logic scripts, preventing duplicate component execution.

Contact & Community

Have technical questions or need help with Agamotto? Connect with us:

X YouTube Bitbucket Contact