jaction

JAction - Chainable Task Execution

Fluent API for composing complex action sequences in Unity with automatic object pooling, zero-allocation async, and parallel execution support.

When to Use

• Sequential workflows with delays
• Polling conditions (WaitUntil/WaitWhile)
• Repeat loops with intervals
• Game timers and scheduled events
• Zero-GC async operations
• Parallel concurrent executions

Core Concepts

Task Snapshot Isolation

When Execute() or ExecuteAsync() is called, the current task list is snapshotted. Modifications to the JAction after execution starts do NOT affect running executions:

var action = JAction.Create()
    .Delay(1f)
    .Do(static () => Debug.Log("Original"));

var handle = action.ExecuteAsync();

// This task is NOT executed by the handle above - it was added after the snapshot
action.Do(static () => Debug.Log("Added Later"));

await handle; // Only prints "Original"

This isolation enables safe parallel execution where each handle operates on its own task snapshot.

Return Types

JActionExecution (returned by Execute, awaited from ExecuteAsync):

• .Action - The JAction that was executed
• .Cancelled - Whether THIS specific execution was cancelled
• .Executing - Whether the action is still executing
• .Dispose() - Returns JAction to pool

JActionExecutionHandle (returned by ExecuteAsync before await):

• .Action - The JAction being executed
• .Cancelled - Whether this execution is cancelled
• .Executing - Whether still running
• .Cancel() - Cancel THIS specific execution
• .AsUniTask() - Convert to UniTask<JActionExecution>
• Awaitable: await handle returns JActionExecution

API Reference

Execution

Method	Returns	Description
.Execute(timeout)	JActionExecution	Synchronous blocking execution
.ExecuteAsync(timeout)	JActionExecutionHandle	Async via PlayerLoop (recommended)

Actions

Method	Description
.Do(Action)	Execute synchronous action
.Do<T>(Action<T>, T)	Execute with state (zero-alloc for reference types)
.Do(Func<JActionAwaitable>)	Execute async action
.Do<T>(Func<T, JActionAwaitable>, T)	Async with state

Timing

Method	Description
.Delay(seconds)	Wait specified seconds
.DelayFrame(frames)	Wait specified frame count
.WaitUntil(condition, frequency, timeout)	Wait until condition true
.WaitWhile(condition, frequency, timeout)	Wait while condition true

Loops

Method	Description
.Repeat(action, count, interval)	Repeat N times
.RepeatWhile(action, condition, frequency, timeout)	Repeat while condition true
.RepeatUntil(action, condition, frequency, timeout)	Repeat until condition true

All loop methods have <TState> overloads for zero-allocation with reference types.

Configuration

Method	Description
.Parallel()	Enable concurrent execution mode
.OnCancel(callback)	Register cancellation callback
.Cancel()	Stop ALL active executions
.Reset()	Clear state for reuse
.Dispose()	Return to object pool

Static Members

Member	Description
JAction.Create()	Get pooled instance
JAction.PooledCount	Check available pooled instances
JAction.ClearPool()	Empty the pool

Patterns

Basic Sequence

using var result = await JAction.Create()
    .Do(static () => Debug.Log("Step 1"))
    .Delay(1f)
    .Do(static () => Debug.Log("Step 2"))
    .ExecuteAsync();

Always Use using var (CRITICAL)

// CORRECT - auto-disposes and returns to pool
using var result = await JAction.Create()
    .Do(() => LoadAsset())
    .WaitUntil(() => assetLoaded)
    .ExecuteAsync();

// WRONG - memory leak, never returns to pool
await JAction.Create()
    .Do(() => LoadAsset())
    .ExecuteAsync();

Parallel Execution with Per-Execution Cancellation

var action = JAction.Create()
    .Parallel()
    .Do(static () => Debug.Log("Start"))
    .Delay(5f)
    .Do(static () => Debug.Log("Done"));

// Start multiple concurrent executions (each gets own task snapshot)
var handle1 = action.ExecuteAsync();
var handle2 = action.ExecuteAsync();

// Cancel only the first execution
handle1.Cancel();

// Each has independent Cancelled state
var result1 = await handle1;  // result1.Cancelled == true
var result2 = await handle2;  // result2.Cancelled == false

action.Dispose();

UniTask.WhenAll with Parallel

var action = JAction.Create()
    .Parallel()
    .Delay(1f)
    .Do(static () => Debug.Log("Done"));

var handle1 = action.ExecuteAsync();
var handle2 = action.ExecuteAsync();

await UniTask.WhenAll(handle1.AsUniTask(), handle2.AsUniTask());

action.Dispose();

Zero-Allocation with Reference Types

// CORRECT - static lambda + reference type state = zero allocation
var data = new MyData();
JAction.Create()
    .Do(static (MyData d) => d.Process(), data)
    .Execute();

// Pass 'this' when inside a class - no wrapper needed
public class Enemy : MonoBehaviour
{
    public bool IsStunned;

    public void ApplyStun(float duration)
    {
        IsStunned = true;
        JAction.Create()
            .Delay(duration)
            .Do(static (Enemy self) => self.IsStunned = false, this)
            .ExecuteAsync().Forget();
    }
}

// Value types use closures (boxing would defeat zero-alloc anyway)
int count = 5;
JAction.Create()
    .Do(() => Debug.Log($"Count: {count}"))
    .Execute();

Timeout Handling

using var result = await JAction.Create()
    .WaitUntil(() => networkReady)
    .ExecuteAsync(timeout: 30f);

if (result.Cancelled)
    Debug.Log("Timed out!");

Cancellation Callback

var action = JAction.Create()
    .OnCancel(() => Debug.Log("Cancelled!"))
    .Delay(10f);

var handle = action.ExecuteAsync();
handle.Cancel();  // Triggers OnCancel callback

Game Patterns

Cooldown Timer

public class AbilitySystem
{
    public bool CanUse = true;

    public async UniTaskVoid TryUseAbility(float cooldown)
    {
        if (!CanUse) return;
        CanUse = false;

        PerformAbility();

        // Pass 'this' as state - no extra class needed
        using var _ = await JAction.Create()
            .Delay(cooldown)
            .Do(static s => s.CanUse = true, this)
            .ExecuteAsync();
    }
}

Damage Over Time

public sealed class DoTState
{
    public IDamageable Target;
    public float DamagePerTick;
}

public static async UniTaskVoid ApplyDoT(
    IDamageable target, float damage, int ticks, float interval)
{
    var state = JObjectPool.Shared<DoTState>().Rent();
    state.Target = target;
    state.DamagePerTick = damage;

    using var _ = await JAction.Create()
        .Repeat(
            static s => s.Target?.TakeDamage(s.DamagePerTick),
            state, count: ticks, interval: interval)
        .ExecuteAsync();

    state.Target = null;
    JObjectPool.Shared<DoTState>().Return(state);
}

Wave Spawner

public async UniTask RunWaves(WaveConfig[] waves)
{
    foreach (var wave in waves)
    {
        using var result = await JAction.Create()
            .Do(() => UI.ShowWaveStart(wave.Number))
            .Delay(2f)
            .Do(() => SpawnWave(wave))
            .WaitUntil(() => ActiveEnemyCount == 0, timeout: 120f)
            .Delay(wave.DelayAfter)
            .ExecuteAsync();

        if (result.Cancelled) break;
    }
}

Health Regeneration

public sealed class RegenState
{
    public float Health, MaxHealth, HpPerTick;
}

public static async UniTaskVoid StartRegen(RegenState state)
{
    using var _ = await JAction.Create()
        .RepeatWhile(
            static s => s.Health = MathF.Min(s.Health + s.HpPerTick, s.MaxHealth),
            static s => s.Health < s.MaxHealth,
            state, frequency: 0.1f)
        .ExecuteAsync();
}

Troubleshooting

Problem	Cause	Solution
Nothing happens	Forgot to call Execute/ExecuteAsync	Add .ExecuteAsync() at the end
Memory leak	Missing using var	Always use using var result = await ...
Frame drops	Using Execute()	Switch to ExecuteAsync()
GC allocations	Closures with reference types	Use static lambda + state parameter
Unexpected timing	Value type state	Wrap in reference type or use closure
Handle shows wrong Cancelled	Reading after modification	Snapshot is isolated - this is expected

Common Mistakes

1. Missing using var - Memory leak, JAction never returns to pool
2. Using Execute() in production - Blocks main thread, causes frame drops
3. State overloads with value types - Causes boxing; use closures instead
4. Forgetting Execute/ExecuteAsync - Nothing happens
5. Heavy work in .Do() - Callbacks run atomically; keep them lightweight
6. Using action.Cancel() in parallel - Cancels ALL executions; use handle.Cancel() for specific execution
7. Modifying JAction after ExecuteAsync - Changes don't affect running execution (task snapshot isolation)