chore: Adds AI instructions and SKILLs for ModernUO codebase (#2347)
Summary
- Adds CLAUDE.md at repo root with 14 terse code audit rules (always loaded, low token cost)
- Adds pointer files for other AI tools: AGENTS.md (Codex), GEMINI.md, .github/COPILOT-INSTRUCTIONS.md (Copilot), .cursorrules (Cursor) — all redirect to CLAUDE.md as single source of truth
- Gitignores /.claude so personal AI config isn't distributed
- Moves Claude skills to dev-docs/claude-skills/ (opt-in, not auto-loaded)
- Adds 14 dev-docs covering codebase conventions
Code Audit Rules (in CLAUDE.md)
1. LINQ tiered rules (Tier 1 free, Tier 2 warm, Tier 3 forbidden)
2. No Console.WriteLine — use LogFactory.GetLogger()
3. No concurrency primitives in game code
4. No World.Mobiles/World.Items iteration
5. Clean up refs in OnDelete()/OnAfterDelete()
6. Cancel timers in OnDelete()/OnAfterDelete()
7. STArrayPool<T>.Shared not ArrayPool<T>.Shared
8. PooledRefList<T> not new List<T>() on hot paths
9. Serialization: partial class, [Constructible], no serialized TimerExecutionToken
10. No Task.Run/new Thread() in game code
11. Never assume era — ask which expansion
12. _camelCase fields, PascalCase properties/methods
13. No empty gumps — use DisplayTo() pattern
14. PropertyList string literals must be {} holes, cliloc-as-argument uses :#
This commit is contained in:
Kamron Batman
GitHub
parent
e77a566f32
commit
1391c563fe
34 changed files with 8549 additions and 0 deletions
287
dev-docs/timers.md
Normal file
287
dev-docs/timers.md
Normal file
|
|
@ -0,0 +1,287 @@
|
|||
# ModernUO Timer System
|
||||
|
||||
This document covers ModernUO's timer system: the timer wheel scheduler, delay calls, timer execution tokens, and patterns for timer usage in game content.
|
||||
|
||||
## Overview
|
||||
|
||||
ModernUO uses a 3-layer hierarchical timer wheel for scheduling delayed and recurring actions. The system is single-threaded and processes timers during each game loop tick.
|
||||
|
||||
> **Timer vs EventScheduler**: The timer wheel is for **game-tick** delays and repeats (8ms precision, sub-second to ~16 days). For **wall-clock/calendar** scheduling — daily resets, weekly events, holiday seasons — use `EventScheduler` instead (1-second granularity, timezone-aware, calendar recurrence patterns). See `dev-docs/event-scheduler.md`.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Timer Wheel
|
||||
3-layer wheel with 4096 slots per layer:
|
||||
|
||||
| Layer | Resolution | Range |
|
||||
|---|---|---|
|
||||
| 0 | 8ms | ~32.8 seconds |
|
||||
| 1 | ~32.8s | ~22 minutes |
|
||||
| 2 | ~22m | ~16 days |
|
||||
|
||||
- Tick rate: 8ms (minimum precision)
|
||||
- All delays are rounded up to nearest 8ms boundary
|
||||
- O(1) insert and remove operations
|
||||
|
||||
### Execution Flow
|
||||
1. `Timer.Slice(tickCount)` called each game loop iteration
|
||||
2. Wheel rotates to current slot
|
||||
3. All timers in the slot are executed via `OnTick()`
|
||||
4. Repeating timers are re-inserted at next interval
|
||||
5. Finished timers call `OnDetach()` for cleanup
|
||||
|
||||
## API Reference
|
||||
|
||||
### Timer.StartTimer (Fire-and-Forget with Pooling)
|
||||
|
||||
Preferred for most use cases. Timers are automatically pooled for reuse.
|
||||
|
||||
```csharp
|
||||
// Immediate execution
|
||||
Timer.StartTimer(callback);
|
||||
|
||||
// Delayed execution
|
||||
Timer.StartTimer(TimeSpan.FromSeconds(5), callback);
|
||||
|
||||
// Repeating
|
||||
Timer.StartTimer(TimeSpan.FromSeconds(1), TimeSpan.FromSeconds(1), callback);
|
||||
|
||||
// Repeating with count limit
|
||||
Timer.StartTimer(TimeSpan.FromSeconds(0), TimeSpan.FromSeconds(1), 10, callback);
|
||||
|
||||
// Delayed start, then repeating
|
||||
Timer.StartTimer(TimeSpan.FromSeconds(5), TimeSpan.FromSeconds(1), callback);
|
||||
```
|
||||
|
||||
### Timer.StartTimer with Token (Cancellable)
|
||||
|
||||
Use when you need to cancel the timer later.
|
||||
|
||||
```csharp
|
||||
private TimerExecutionToken _token;
|
||||
|
||||
// Start with token
|
||||
Timer.StartTimer(TimeSpan.FromSeconds(5), DoWork, out _token);
|
||||
|
||||
// Check state
|
||||
if (_token.Running) { }
|
||||
var remaining = _token.RemainingCount; // int.MaxValue if infinite
|
||||
var next = _token.Next; // DateTime of next tick
|
||||
var index = _token.Index; // Times ticked so far
|
||||
|
||||
// Cancel (safe to call multiple times)
|
||||
_token.Cancel();
|
||||
```
|
||||
|
||||
### Timer.DelayCall (Returns Timer Object)
|
||||
|
||||
Legacy-style API that returns the timer object directly.
|
||||
|
||||
```csharp
|
||||
var timer = Timer.DelayCall(TimeSpan.FromSeconds(5), DoWork);
|
||||
timer.Stop(); // Cancel
|
||||
|
||||
// With state parameters (avoids lambda allocation)
|
||||
Timer.DelayCall(TimeSpan.FromSeconds(2), ProcessTarget, mobile, item);
|
||||
Timer.DelayCall(TimeSpan.FromSeconds(1), DoWork, arg1, arg2, arg3);
|
||||
// Supports up to 5 state parameters
|
||||
```
|
||||
|
||||
### Timer.Pause (Awaitable)
|
||||
|
||||
For async/await patterns:
|
||||
|
||||
```csharp
|
||||
await Timer.Pause(TimeSpan.FromMilliseconds(100));
|
||||
await Timer.Pause(500); // Milliseconds overload
|
||||
```
|
||||
|
||||
Safe because `EventLoopContext` routes continuations to the main thread.
|
||||
|
||||
## TimerExecutionToken
|
||||
|
||||
Lightweight struct for tracking fire-and-forget timers:
|
||||
|
||||
```csharp
|
||||
public struct TimerExecutionToken
|
||||
{
|
||||
public bool Running { get; } // Is timer still active?
|
||||
public int Index { get; } // How many times OnTick fired
|
||||
public int RemainingCount { get; } // Ticks remaining (int.MaxValue if infinite)
|
||||
public DateTime Next { get; } // When next tick fires
|
||||
public void Cancel(); // Stop and return to pool
|
||||
}
|
||||
```
|
||||
|
||||
Key behaviors:
|
||||
- `Cancel()` is safe to call multiple times
|
||||
- Default value (`default(TimerExecutionToken)`) has `Running = false`
|
||||
- NOT serializable -- restore in `[AfterDeserialization]`
|
||||
|
||||
## Patterns
|
||||
|
||||
### Pattern 1: Simple Delayed Action
|
||||
```csharp
|
||||
// Delete item after 10 seconds
|
||||
Timer.StartTimer(TimeSpan.FromSeconds(10), Delete);
|
||||
```
|
||||
|
||||
### Pattern 2: Cancellable Recurring Timer
|
||||
```csharp
|
||||
private TimerExecutionToken _checkTimer;
|
||||
|
||||
public MyItem() : base(0x1234)
|
||||
{
|
||||
Timer.StartTimer(
|
||||
TimeSpan.FromSeconds(5), // Initial delay
|
||||
TimeSpan.FromSeconds(5), // Repeat interval
|
||||
CheckExpiry, // Callback
|
||||
out _checkTimer // Token for cancellation
|
||||
);
|
||||
}
|
||||
|
||||
public override void OnAfterDelete()
|
||||
{
|
||||
_checkTimer.Cancel();
|
||||
base.OnAfterDelete();
|
||||
}
|
||||
|
||||
private void CheckExpiry()
|
||||
{
|
||||
if (Core.Now >= _expireTime)
|
||||
Delete();
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 3: Timer Restoration After Deserialization
|
||||
```csharp
|
||||
[SerializationGenerator(0, false)]
|
||||
public partial class TimedItem : Item
|
||||
{
|
||||
private TimerExecutionToken _timer; // NOT serialized
|
||||
|
||||
[SerializableField(0)]
|
||||
[DeltaDateTime]
|
||||
private DateTime _expireTime;
|
||||
|
||||
[Constructible]
|
||||
public TimedItem() : base(0x1234)
|
||||
{
|
||||
_expireTime = Core.Now + TimeSpan.FromHours(1);
|
||||
StartTimer();
|
||||
}
|
||||
|
||||
private void StartTimer()
|
||||
{
|
||||
Timer.StartTimer(TimeSpan.FromMinutes(1), TimeSpan.FromMinutes(1), Check, out _timer);
|
||||
}
|
||||
|
||||
[AfterDeserialization]
|
||||
private void AfterDeserialization() => StartTimer();
|
||||
|
||||
public override void OnAfterDelete()
|
||||
{
|
||||
_timer.Cancel();
|
||||
base.OnAfterDelete();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 4: Serializable Timer Field
|
||||
```csharp
|
||||
[SerializableField(0, setter: "private")]
|
||||
private Timer _decayTimer;
|
||||
|
||||
[DeserializeTimerField(0)]
|
||||
private void DeserializeDecayTimer(TimeSpan delay)
|
||||
{
|
||||
_decayTimer = Timer.DelayCall(delay, Delete);
|
||||
_decayTimer.Start();
|
||||
}
|
||||
|
||||
public void BeginDecay(TimeSpan delay)
|
||||
{
|
||||
_decayTimer?.Stop();
|
||||
_decayTimer = new InternalTimer(this, delay);
|
||||
_decayTimer.Start();
|
||||
}
|
||||
|
||||
public override void OnAfterDelete()
|
||||
{
|
||||
_decayTimer?.Stop();
|
||||
_decayTimer = null;
|
||||
base.OnAfterDelete();
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 5: Custom Timer Class
|
||||
```csharp
|
||||
private class DecayTimer : Timer
|
||||
{
|
||||
private readonly Corpse _corpse;
|
||||
|
||||
public DecayTimer(Corpse c, TimeSpan delay) : base(delay)
|
||||
{
|
||||
_corpse = c;
|
||||
}
|
||||
|
||||
protected override void OnTick()
|
||||
{
|
||||
if (!_corpse.GetFlag(CorpseFlag.NoBones))
|
||||
_corpse.TurnToBones();
|
||||
else
|
||||
_corpse.Delete();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 6: State-Carrying Delay (No Lambda)
|
||||
```csharp
|
||||
// Instead of lambda (allocates closure):
|
||||
Timer.StartTimer(TimeSpan.FromSeconds(2), () => ProcessTarget(from, target));
|
||||
|
||||
// Use state parameters (no allocation):
|
||||
Timer.DelayCall(TimeSpan.FromSeconds(2), ProcessTarget, from, target);
|
||||
|
||||
private static void ProcessTarget(Mobile from, Mobile target)
|
||||
{
|
||||
// Process...
|
||||
}
|
||||
```
|
||||
|
||||
## Timer Pool
|
||||
|
||||
Timers created via `Timer.StartTimer()` are pooled for reuse:
|
||||
- Initial pool: 1024 timers (configurable: `timer.initialPoolCapacity`)
|
||||
- Max pool: 16x initial (configurable: `timer.maxPoolCapacity`)
|
||||
- Pool refills asynchronously when depleted
|
||||
- `Timer.CheckTimerPool()` called each game loop to monitor
|
||||
|
||||
## ISerializableExtensions for Timers
|
||||
|
||||
```csharp
|
||||
// Extension methods on ISerializable:
|
||||
entity.Stop(timer); // Stop + MarkDirty
|
||||
entity.Start(timer); // Start + MarkDirty
|
||||
entity.Restart(timer, delay, interval); // Stop + reconfigure + Start + MarkDirty
|
||||
entity.Stop(ref timer); // Stop + null + MarkDirty
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
| Mistake | Problem | Fix |
|
||||
|---|---|---|
|
||||
| Serializing `TimerExecutionToken` | Build error / data corruption | Leave unserialized, use `[AfterDeserialization]` |
|
||||
| Not cancelling on delete | Timer fires on deleted entity | Cancel in `OnDelete()`/`OnAfterDelete()` |
|
||||
| Using `Thread.Sleep` | Blocks game loop | Use `await Timer.Pause()` |
|
||||
| Creating timer in deserialization | Timer starts before world is ready | Use `[AfterDeserialization]` |
|
||||
| Lambda in hot-path timer | Allocates closure every time | Use state parameters |
|
||||
|
||||
## Key File References
|
||||
- Timer base class: `Projects/Server/Timer/Timer.cs`
|
||||
- DelayCall + StartTimer: `Projects/Server/Timer/Timer.DelayCall.cs`
|
||||
- Timer wheel: `Projects/Server/Timer/Timer.TimerWheel.cs`
|
||||
- Pool management: `Projects/Server/Timer/Timer.Pool.cs`
|
||||
- State timers: `Projects/Server/Timer/Timer.DelayStateCall.cs`
|
||||
- Token: `Projects/Server/Timer/TimerExecutionToken.cs`
|
||||
- Serializable extensions: `Projects/Server/Serialization/ISerializableExtensions.cs`
|
||||
Loading…
Add table
Add a link
Reference in a new issue