# Time Fracture — Timeline time control for Unity 6
> New here? Open `00-Start-Here.md` for the learning path, then `TimeFracture-Getting-Started.md` for step-by-step setup.
Drives `PlayableDirector`s by hand so each Timeline can play forward, rewind, change speed, freeze,
skip, loop, or follow a remixed playlist of segments. Any number of objects can run their own
Timelines at the same time, and groups let you bend time for many of them at once.
Requires the **Timeline** package (`com.unity.timeline`, installed by default in Unity 6).
Uses the **Input System package** only. Set **Project Settings ▸ Player ▸ Active Input Handling** to
**Input System Package (New)**. Player-facing controls are Input Action properties: edit their bindings in
the Inspector, or tick **Use Reference** to use actions from your own `.inputactions` asset. The debug HUD
reads the keyboard directly through the Input System.
## Quick start
1. **Tools ▸ Time Fracture ▸ Build Demo Scene** builds a working scene in `Assets/TimeFractureDemo`.
It has three actors on three Timelines running at once, plus segments, events, a remix, and a branch.
2. Press Play. The HUD in the top-left shows each channel. Keys: **Tab** selects a channel,
**Space** pauses, **R** reverses, **F** freezes, **←/→** skip, **↑/↓** change the rate,
**L** loops the current segment, **B** breaks the loop, **P** plays a playlist, **S** shuffles it,
**1–9** jump to a segment, **G** rewinds the whole world, **H** hides the HUD.
To use it on your own objects:
1. Give the object a `PlayableDirector` with a Timeline asset.
2. Add **Time Channel** to the same object. It switches the director to Manual mode and takes over playback.
3. Set the **Channel Id** (the name commands use) and the **Groups** list (for example `World`, `Clocks`).
## The pieces
| Component / asset | What it does |
|---|---|
| `TimeChannel` | One per director. Handles playback, rate, freeze, jump, skip, loops, playlists and markers. |
| `TimeWorld` (static) | Holds the registry of channels, the named groups, the world scale, and story flags. Also routes commands. |
| `Time Segment` marker | Placed on the Timeline's Markers lane. Marks where a named segment starts; the segment runs to the next segment marker. You can also type segments into the channel's **Segments** list. |
| `Time Event` marker | Placed on any track. Fires when the playhead crosses it going forward, backward or both. It can also run commands. |
| `TimeCommand` | One instruction, such as "EaseRate group Clocks to −1" or "JumpToSegment Escape if flag DoorOpen". |
| `TimeCommandTrigger` | The interaction layer. Runs a list of commands on a physics trigger, a Time Event, a flag change, or when something calls `Fire()` (a UI Button, an input action, or your own script). |
| `TimeChannelDebugHUD` | An on-screen readout with keyboard controls, for testing. |
To add the markers, right-click the Markers lane (or a track's marker area) in the Timeline window
and choose **Add ▸ Time Fracture ▸ …**.
## Effective speed
```
effective rate = channel rate × (scale of each group the channel is in) × world scale
```
A negative result runs time backward. A channel stops if it is paused, or if it, any of its groups,
or the world is frozen.
## Scripting cheat sheet
```csharp
using TimeFracture;
var door = TimeWorld.Find("Door"); // or GetComponent<TimeChannel>()
// speed & direction
door.SetRate(-1); // rewind
door.EaseRate(0.2f, 3f); // smoothly slow to 0.2x
door.Reverse();
TimeWorld.SetGroupScale("Clocks", -1, 2f); // ease every clock into rewind
TimeWorld.WorldScale = 0.5f; // slow everything
// freeze
door.FreezeFor(2f);
TimeWorld.FreezeGroup("Enemies", true);
// skip
door.JumpTo(4.5);
door.JumpToSegment("Opened");
door.Skip(-3); // jump back 3 story-seconds (follows loops/playlists)
// loop
door.LoopSegment("Creak"); // loop until BreakLoop()
door.LoopCurrent(2); // loop whatever is playing 2 more times
door.BreakLoop(); // finish this pass, then carry on
// remix
door.PlaySegment("Slam", reverse: true, speed: 2f);
door.PlaySegments("C", "A", "B"); // a playlist built in code
door.PlayPlaylist("Nightmare"); // a playlist from the inspector
door.ShufflePlaylist();
door.ReversePlaylist(); // reverses the order and flips each step's direction
// branching
TimeWorld.SetFlag("HasKey");
TimeWorld.Execute(new TimeCommand(TimeAction.JumpToSegment) { text = "Escape", onlyIfFlag = "HasKey" }, door);
// listening
door.EventFired += e => Debug.Log(
quot;{e.id} {(e.IsReverse ? "rewound past" : "reached")} at {e.time}");
TimeWorld.AnyEvent += e => { /* any channel */ };
```
## Playlists (remixes)
A playlist is a list of steps. Each step has its own settings:
- `segment`: the segment to play. Leave it empty to play the whole timeline.
- `reverse`: play the step backward.
- `speed`: a multiplier for this step only.
- `repeats`: extra passes. `-1` loops the step until `BreakLoop()` is called.
- `holdAfter`: seconds to freeze on the last frame before moving on.
If the world, a group, or the channel's rate goes negative while a playlist is running, the playlist
rewinds step by step, so you can undo a remix in the same way you would undo plain playback.
## Branching story with flags
When you add a `TimeCommand` to a Time Event marker, you can set **Only If Flag**. The command then
runs only when that flag has the value you chose. The demo's walker works like this:
- At 7.5 s a marker runs *"JumpToSegment Middle if Paradox"*, so the walker relives the middle of its
story only after the player has set that flag.
- A `TimeCommandTrigger` set to *OnFlagChanged* puts the speed back to normal once the flag clears.
Flags are global: `TimeWorld.SetFlag`, `GetFlag`, `ToggleFlag`, and the `FlagChanged` event.
## Things to know
- **Markers that you jump over.** `JumpTo` and `Skip` do not fire the markers they pass over. If you
want them to, turn on **Fire Events On Jump** on the channel. Markers exactly at the spot you land on
stay armed, so they still fire.
- **Signals.** Timeline does not fire Signal Emitters during manual evaluation, so the channel fires them
itself and sends them to the `SignalReceiver` on the bound object (or on the director's object for the
Markers lane). By default they fire only when time runs forward; **Signals Fire In Reverse** changes that.
- **Audio tracks** do not play while a director is in Manual mode, and audio can't play in reverse
anyway. Trigger sounds from Time Events instead, and choose ForwardOnly or Both for each one.
- **Nested timelines** (Control Track sub-timelines) are evaluated correctly, but markers inside them
are not scanned. Put the markers on the parent timeline.
- **Scripts that aren't on a Timeline** (physics, Animators, particles) can follow the clock by reading
`channel.EffectiveRate` or `TimeWorld.ScaleFor(groups)`.
- **Timelines play the same way every time.** Rewinding doesn't need any recorded snapshots: it simply
evaluates the Timeline at an earlier time.
## More tutorials
- `TimeFracture-Getting-Started.md`: step-by-step project setup and your first Time Channel, segments, playlists, events, groups and branching.
- `TimeFracture-Tutorial-Wiring.md`: player interaction, timeline visuals and lenses, shared timelines, and recording with echoes.
- `TimeFracture-Tutorial-Enemies.md`: rewindable AI enemies, physics props and bullets (`TimeRewindable`, `ITimeStateful`), with the **Build Enemy Rewind Demo (2D)** menu.
- `TimeFracture-Design-Ideas.md`: similar games, player motivations and level ideas.