GameCore.Timers

Awaitable 双端

命名空间 GameCore.Timers

public abstract class Awaitable<TResult> : Task, IThinker, INotifyCompletion where TResult : notnull

Represents an abstract awaitable task that can be used with async/await patterns while integrating with the game's thinking and tick systems.

• token — Optional cancellation token to monitor for cancellation requests.
• allowSynchronousStop — Whether the task can be stopped immediately or must wait for the next tick finalizer.

备注

This class bridges the gap between the game's tick-based execution model and C#'s async/await functionality. It provides a foundation for creating game-specific awaitable operations such as delays, animations, and other time-based tasks that need to execute over multiple game frames. The class implements both the game's IThinker interface for tick-based processing and the .NET INotifyCompletion interface for async/await support.

构造函数

Awaitable 双端

protected Awaitable(CancellationToken? token = null, bool allowSynchronousStop = false)

Represents an abstract awaitable task that can be used with async/await patterns while integrating with the game's thinking and tick systems.

• token — Optional cancellation token to monitor for cancellation requests.
• allowSynchronousStop — Whether the task can be stopped immediately or must wait for the next tick finalizer.

备注

This class bridges the gap between the game's tick-based execution model and C#'s async/await functionality. It provides a foundation for creating game-specific awaitable operations such as delays, animations, and other time-based tasks that need to execute over multiple game frames. The class implements both the game's IThinker interface for tick-based processing and the .NET INotifyCompletion interface for async/await support.

属性

Result 双端

public TaskResult<TResult> Result { get; }

Gets the result of the task, either the actual result if completed or the current status.

备注

This property provides a way to access the result without blocking. If the task is completed, it returns the actual result; otherwise, it returns the current task status.

方法

Start 双端

public override void Start()

Starts the awaitable task and begins processing if necessary.

备注

This method initiates the task execution and determines whether it needs to continue thinking on subsequent frames. If the task can complete immediately, it will be stopped synchronously or scheduled for finalization depending on the allowSynchronousStop setting.

GetAwaiter 双端

public Awaitable<TResult> GetAwaiter()

Gets the awaiter for this awaitable task, enabling async/await syntax.

返回： This awaitable instance, which serves as its own awaiter.

备注

This method is required for async/await support and allows the awaitable to be used directly in await expressions without requiring a separate awaiter object.

ThinkAction 双端

protected abstract void ThinkAction(int delta)

Performs the specific thinking action for this awaitable task.

• delta — The time delta since the last tick in milliseconds.

备注

This abstract method must be implemented by derived classes to define what happens during each tick while the awaitable is active. This is where the core logic for progress tracking, countdown timers, or other time-based operations should be implemented.

ThinkFinish 双端

protected abstract bool ThinkFinish()

Determines whether this awaitable task should finish execution.

返回： True if the task should complete; otherwise, false to continue thinking.

备注

This abstract method must be implemented by derived classes to define the completion condition for the awaitable. It's called after each ThinkAction to determine if the task has reached its completion criteria.

GetResult 双端

public abstract TResult GetResult()

Gets the result value of this awaitable task.

返回： The result produced by this awaitable task.

备注

This abstract method must be implemented by derived classes to provide the final result of the awaitable operation. It's called when the async/await operation completes.

ContinueWith 双端

public Awaitable<TResult> ContinueWith(Action<Awaitable<TResult>> continuationAction)

Stop 双端

protected override bool Stop(bool completed)

Stops the awaitable task and disables thinking.

• completed — True if the task is stopping because it completed successfully; false for cancellation.

返回： True if the stop operation was initiated successfully; otherwise, false.

备注

This method extends the base Task stop behavior by also disabling the thinking process to prevent unnecessary tick processing after the task has been stopped.

StopSynchronous 双端

protected override bool StopSynchronous(bool completed)

Immediately stops the awaitable task, disables thinking, and executes any pending continuation.

• completed — True if the task completed successfully; false if it was cancelled.

返回： True if the task was stopped successfully; otherwise, false.

备注

This method performs the actual stopping logic including disabling thinking, executing the continuation callback if the task completed successfully, and cleaning up resources.

Delay 双端

命名空间 GameCore.Timers

public class Delay : Awaitable<int>

Represents an awaitable delay that can be used to pause execution for a specified duration in game time or real time.

备注

This class provides a way to create delays in game logic that can be adjusted based on frame timing. The delay can be paused, resumed, and configured to account for frame delta time variations. It integrates seamlessly with async/await patterns while working with the game's tick system.

构造函数

Delay 双端

public Delay(TimeSpan time, CancellationToken? token = null, int adjustment = 0, bool allowSynchronousStop = false)

Initializes a new instance of the Delay class with a TimeSpan duration.

• time — The duration to delay execution.
• token — Optional cancellation token to monitor for cancellation requests.
• adjustment — Optional time adjustment in milliseconds to add to the delay duration.
• allowSynchronousStop — Whether the delay can be stopped immediately or must wait for the next tick finalizer.

备注

This constructor converts the TimeSpan to milliseconds and delegates to the milliseconds constructor. The delay starts immediately upon construction.

Delay 双端

public Delay(int timeInMilliseconds, CancellationToken? token = null, int adjustment = 0, bool allowSynchronousStop = false)

Initializes a new instance of the Delay class with a duration in milliseconds.

• timeInMilliseconds — The duration to delay execution in milliseconds.
• token — Optional cancellation token to monitor for cancellation requests.
• adjustment — Optional time adjustment in milliseconds to add to the delay duration.
• allowSynchronousStop — Whether the delay can be stopped immediately or must wait for the next tick finalizer.

备注

The delay starts immediately upon construction. The adjustment parameter can be used to fine-tune the delay duration, which is useful for synchronization or timing corrections.

属性

AdjustByFrameDelta 双端

public bool AdjustByFrameDelta { get; set; }

Gets or sets a value indicating whether the delay should be adjusted based on the frame delta time.

备注

When set to false, the delay counts each game tick as a fixed duration based on FramePerSecond. When set to true, the delay is adjusted by the delta time of each frame, making it more accurate to real time. However, setting this to true may cause jittery behavior if the frame rate is inconsistent.

RemainingTime 双端

public TimeSpan RemainingTime { get; }

Gets the remaining time before the delay completes.

备注

This property provides real-time access to how much time is left in the delay. Once the delay completes, this value will be zero or negative.

Priority 双端

public int? Priority { get; }

Gets the priority value used for scheduling this delay in the thinking system.

备注

This property is used internally by the game's scheduling system to optimize the order of delay processing. Lower values indicate higher priority.

方法

Pause 双端

public void Pause(bool on)

Pauses or resumes the delay execution.

• on — True to pause the delay; false to resume it.

备注

When paused, the delay will stop counting down and remain at its current remaining time. This method has no effect if the delay has already completed. Pausing a delay effectively stops its thinking process until resumed.

SetRemainingTime 双端

public bool SetRemainingTime(TimeSpan remainingTime)

Sets the remaining time for the delay to a new value.

• remainingTime — The new remaining time for the delay.

返回： True if the remaining time was successfully set; false if the delay has already completed.

备注

This method allows you to modify the remaining time of an active delay, which can be useful for extending or shortening delays based on game events or conditions. The method has no effect if the delay has already completed.

ThinkAction 双端

protected override void ThinkAction(int delta)

Performs the delay countdown logic on each game tick.

• delta — The time delta since the last tick in milliseconds.

备注

This method is called automatically by the thinking system. It decrements the remaining time either by the actual frame delta (if AdjustByFrameDelta is true) or by the fixed frame duration.

ThinkFinish 双端

protected override bool ThinkFinish()

Determines whether the delay should finish execution.

返回： True if the delay time has elapsed; otherwise, false.

备注

This method is called after each ThinkAction to determine if the delay has reached its completion condition (remaining time <= 0).

GetResult 双端

public override int GetResult()

Gets the result value of the delay when it completes.

返回： The remaining time in milliseconds when the delay finished (typically zero or negative).

备注

This method is called by the await mechanism when the delay completes. The returned value represents how much time was remaining when the delay finished, which can be useful for timing calculations or detecting early completion.

DelayTill 双端

命名空间 GameCore.Timers

public class DelayTill : Awaitable<bool>

Represents an awaitable operation that waits until a specified condition becomes true.

备注

This class provides a way to pause execution until a custom condition is satisfied. The condition is checked every game tick until it returns true. This is useful for waiting on game state changes, entity conditions, or other dynamic criteria.

构造函数

DelayTill 双端

public DelayTill(Func<bool> condition, CancellationToken? token = null, bool allowSynchronousStop = false)

Initializes a new instance of the DelayTill class with the specified condition.

• condition — A function that returns true when the wait condition is satisfied.
• token — An optional cancellation token to cancel the wait operation.
• allowSynchronousStop — Whether the operation can complete synchronously if the condition is already true.

备注

The condition function will be called every game tick until it returns true or the operation is cancelled.

方法

GetResult 双端

public override bool GetResult()

Gets the result of the conditional wait operation.

返回： Always returns true when the condition is satisfied.

ThinkAction 双端

protected override void ThinkAction(int delta)

Performs no action during each tick - the condition checking is handled in ThinkFinish.

• delta — The time delta for this tick (unused).

ThinkFinish 双端

protected override bool ThinkFinish()

Determines whether the conditional wait should finish by evaluating the condition.

返回： The result of the condition function.

DelayTillWithTimeout 双端

命名空间 GameCore.Timers

public class DelayTillWithTimeout : Awaitable<int>

Represents an awaitable operation that waits until a specified condition becomes true or a timeout expires.

备注

This class combines conditional waiting with timeout functionality. It will complete when either:

• The specified condition returns true, or
• The timeout period expires The remaining time when the operation completes indicates whether the condition was met (positive value) or the timeout expired (zero or negative value). This is useful for operations that need to wait for game state changes but have a maximum wait time to prevent infinite blocking.

构造函数

DelayTillWithTimeout 双端

public DelayTillWithTimeout(Func<bool> condition, TimeSpan time, CancellationToken? token = null, int adjustment = 0, bool allowSynchronousStop = false)

Initializes a new instance of the DelayTillWithTimeout class with the specified condition and timeout.

• condition — A function that returns true when the wait condition is satisfied.
• time — The maximum time to wait before timing out.
• token — An optional cancellation token to cancel the wait operation.
• adjustment — An optional adjustment value, in milliseconds, to modify the timeout duration.
• allowSynchronousStop — Whether the operation can complete synchronously if the condition is already true.

备注

The operation will complete when either the condition becomes true or the timeout expires. Use GetResult to determine which case occurred by checking if the remaining time is positive.

属性

AdjustByFrameDelta 双端

public bool AdjustByFrameDelta { get; set; }

Gets or sets a value indicating whether the delay should be adjusted based on the frame delta time.

备注

• When set to false, the delay counts each game tick as a fixed duration based on FramePerSecond.
• When set to true, the delay is adjusted by the delta time of each frame, making it more accurate to real time. However, this may cause jittery behavior if the frame rate is inconsistent.

方法

ThinkFinish 双端

protected override bool ThinkFinish()

Determines whether the conditional wait with timeout should finish.

返回： true if the timeout has expired or the condition is satisfied; otherwise, false.

ThinkAction 双端

protected override void ThinkAction(int delta)

Updates the remaining time during each tick of the wait operation.

• delta — The time delta for this tick.

备注

The time reduction depends on the AdjustByFrameDelta setting.

GetResult 双端

public override int GetResult()

Gets the remaining time when the operation completes.

返回： The remaining time in milliseconds. A positive value indicates the condition was satisfied before timeout; zero or negative indicates the timeout expired.

EventWaiter 双端

命名空间 GameCore.Timers

public abstract class EventWaiter<T> : EventWaiter where T : class

Represents an abstract base class for event waiters that are associated with a specific target object.

• target — The target object that this event waiter is associated with.

备注

This generic version of EventWaiter provides a convenient way to create event waiters that are tied to specific objects, such as entities, components, or other game objects. The target object is automatically cleared when the event waiter is cleaned up to prevent memory leaks.

构造函数

EventWaiter 双端

protected EventWaiter(T target)

Represents an abstract base class for event waiters that are associated with a specific target object.

• target — The target object that this event waiter is associated with.

备注

This generic version of EventWaiter provides a convenient way to create event waiters that are tied to specific objects, such as entities, components, or other game objects. The target object is automatically cleared when the event waiter is cleaned up to prevent memory leaks.

方法

ClearUpEvent 双端

protected override void ClearUpEvent()

Clears the target reference to prevent memory leaks.

备注

This implementation of ClearUpEvent sets the Target to null, which helps prevent memory leaks by breaking the reference to the target object. Derived classes can override this method to provide additional cleanup logic while still calling the base implementation.

字段

Target 双端

protected T Target

Gets the target object that this event waiter is associated with.

备注

This property provides access to the target object for derived classes to use in their event subscription logic. The target is automatically set to null during cleanup.

NeverEndingTask 双端

命名空间 GameCore.Timers

public class NeverEndingTask : Task, INotifyCompletion

Represents a task that never completes, designed for scenarios where indefinite waiting is required.

备注

This class provides a way to create awaitable operations that intentionally never complete. It's useful for scenarios where you need to block execution indefinitely, such as waiting for external events that may never occur, or creating placeholder tasks in testing scenarios. Since this task never completes, awaiting it will block the calling code indefinitely unless cancelled through other means.

构造函数

NeverEndingTask 双端

public NeverEndingTask()

方法

GetAwaiter 双端

public NeverEndingTask GetAwaiter()

Gets the awaiter for this never-ending task, enabling async/await syntax.

返回： This task instance, which serves as its own awaiter.

备注

This method is required for async/await support. Since the task never completes, any code awaiting this task will block indefinitely unless interrupted by external means.

GetResult 双端

public void GetResult()

Gets the result of the never-ending task.

备注

Since this task never completes, this method should never be called under normal circumstances. If called, it performs no action as there is no meaningful result to return from a task that never finishes.

NextTick 双端

命名空间 GameCore.Timers

public class NextTick : Awaitable<bool>

Represents an awaitable operation that completes after the next game tick occurs.

备注

This class is useful when you need to delay execution by exactly one frame or game tick. It's commonly used to ensure operations happen after all current frame processing is complete, or to break up long-running operations across multiple frames.

构造函数

NextTick 双端

public NextTick(CancellationToken? token = null)

Initializes a new instance of the NextTick class.

• token — An optional cancellation token to cancel the wait operation.

备注

The operation will complete after the next game tick unless cancelled via the token.

方法

GetResult 双端

public override bool GetResult()

Gets the result of the next tick operation.

返回： Always returns true when the next tick completes.

ThinkAction 双端

protected override void ThinkAction(int delta)

Marks that a tick has occurred during the think operation.

• delta — The time delta for this tick (unused in this implementation).

ThinkFinish 双端

protected override bool ThinkFinish()

Determines whether the next tick operation should finish.

返回： true if a tick has occurred; otherwise, false.

SyncedDelay 双端

命名空间 GameCore.Timers

public class SyncedDelay

A specialized timer that provides server-side precise timing with client-side time synchronization. Used for scenarios where server needs precise control while clients need to display timing information.

备注

This class is designed for use cases like Buff durations, where:

• Server side uses precise Delay for timing control and game logic
• Client side gets synchronized timing information for UI display This class is lighter weight and focused specifically on the timing display use case rather than full cooldown management functionality.

构造函数

SyncedDelay 双端

public SyncedDelay(TimeSpan duration, ICooldownHost cooldownHost, long cooldownHash, CancellationToken? cancellationToken = null, int adjustment = 0)

Initializes a new instance of the SyncedDelay class.

• duration — The duration for the delay.
• cooldownHost — The cooldown host for client synchronization.
• cooldownHash — The unique hash for the cooldown synchronization.
• cancellationToken — Optional cancellation token to monitor for cancellation requests.
• adjustment — Optional time adjustment in milliseconds to add to the duration.

属性

Duration 双端

public TimeSpan Duration { get; }

Gets the total duration of this synced delay.

RemainingTime 双端

public TimeSpan? RemainingTime { get; }

Gets the remaining time before the delay completes.

备注

On the server side, this returns the precise remaining time from the internal Delay object. On the client side, this returns the synchronized time from the cooldown system. When paused, this property returns null on the client side to indicate that the timing display should be hidden.

IsRunning 双端

public bool IsRunning { get; }

Gets a value indicating whether the delay is currently running.

IsCompleted 双端

public bool IsCompleted { get; }

Gets a value indicating whether the delay has completed.

方法

WaitForCompletion 双端

public Task<int> WaitForCompletion()

Starts the delay and returns a task that completes when the delay finishes.

返回： A task that represents the delay operation. The result is the remaining time in milliseconds when completed.

备注

On the server side, this creates the internal Delay object and sets up cooldown synchronization for clients. The returned task will complete when the delay finishes. On the client side, this returns an already completed task since client-side timing is controlled by server synchronization.

Pause 双端

public void Pause(bool paused)

Pauses or resumes the delay execution.

• paused — True to pause the delay; false to resume it.

备注

When paused, the server-side Delay stops counting down and the cooldown synchronization is cleared from clients. When resumed, cooldown synchronization is restarted with the current remaining time. This method has no effect if the delay has not been started or has already completed.

SetRemainingTime 双端

public bool SetRemainingTime(TimeSpan remainingTime)

Sets the remaining time for the delay to a new value.

• remainingTime — The new remaining time for the delay.

返回： True if the remaining time was successfully set; false if the delay has not started or has completed.

备注

This method allows modification of the remaining time of an active delay. Both the server-side delay and client-side synchronization are updated.

Stop 双端

public void Stop()

Stops the delay immediately.

备注

This cancels the server-side delay and clears the client-side cooldown synchronization.

ToString 双端

public override string ToString()

Returns a string representation of the synced delay.

返回： A string containing the delay's duration and remaining time information.

Timer 双端

命名空间 GameCore.Timers

public class Timer : Component, ISupportInitialize

Handles recurring events in an application.

构造函数

Timer 双端

public Timer()

Initializes a new instance of the Timer class, with the properties set to initial values.

Timer 双端

public Timer(double interval)

Initializes a new instance of the Timer class, setting the Interval property to the specified period.

• interval — The time, in milliseconds, between events. The value must be greater than zero and less than or equal to MaxValue.

Timer 双端

public Timer(TimeSpan interval)

Initializes a new instance of the Timer class, setting the Interval property to the specified period.

• interval — The time between events. The value in milliseconds must be greater than zero and less than or equal to MaxValue.

属性

AutoReset 双端

public bool AutoReset { get; set; }

Gets or sets a value indicating whether the Timer raises the Tick event each time the specified Interval has elapsed, when Enabled is set to true.

Enabled 双端

public bool Enabled { get; set; }

Gets or sets a value indicating whether the Timer is able to raise events at a defined interval. The default value by design is false, don't change it.

Interval 双端

public double Interval { get; set; }

Gets or sets the interval on which to raise events.

Site 双端

public override ISite? Site { get; set; }

Sets the enable property in design mode to true by default.

SynchronizingObject 双端

public ISynchronizeInvoke? SynchronizingObject { get; set; }

Gets or sets the object used to marshal event-handler calls that are issued when an interval has elapsed.

IsPaused 双端

public bool IsPaused { get; }

Gets a value indicating whether the timer is currently paused.

RemainingTime 双端

public TimeSpan RemainingTime { get; set; }

Gets or sets the remaining time for the current timer cycle.

备注

Setting this property only affects the current timer cycle. If AutoReset is true, subsequent cycles will use the Interval value. Setting has no effect if the timer is not enabled or has no active delay.

方法

BeginInit 双端

public void BeginInit()

Notifies the object that initialization is beginning and tells it to stand by.

Close 双端

public void Close()

Disposes of the resources (other than memory) used by the Timer.

Dispose 双端

protected override void Dispose(bool disposing)

EndInit 双端

public void EndInit()

Notifies the object that initialization is complete.

Start 双端

public void Start()

Starts the timing by setting Enabled to true.

Stop 双端

public void Stop()

Stops the timing by setting Enabled to false.

Pause 双端

public void Pause()

Pauses the timer, preserving the remaining time of the current cycle. Call Resume to continue from where it was paused.

Resume 双端

public void Resume()

Resumes the timer from the point where it was paused.

Restart 双端

public void Restart()

Restarts the timer from the beginning of its interval.

事件

Elapsed 双端

public event ElapsedEventHandler Elapsed

Occurs when the Interval has elapsed.