Class: Timer
Defined in: handles/timer.ts:18
A timer: a countdown in game seconds that runs a handler when it expires, once or periodically.
Remarks
- Game time follows the game speed, and stands still while the game is paused.
Timer.afterandTimer.everycover the common cases;createthenstartgives a Timer that can be paused, resumed and started again.
Example
A countdown and a delayed call
// A ten-second countdown printed each second: the Timer returned by every
// is the caller's to destroy. Then a one-off call, whose Timer destroys
// itself.
import { Init, Timer } from "reforged-ts";
Init.onGameStart(() => {
let left = 10;
Timer.every(1, (timer) => {
left -= 1;
print(`${String(left)} seconds left`);
if (left === 0) {
timer.destroy();
}
});
Timer.after(10.5, () => {
print("Go!");
});
});
Native
Extends
Handle<timer>
Properties
handle
readonlyhandle:timer
Defined in: handles/handle.ts:132
The Handle this Wrapper owns, to pass to a Native the library does not wrap.
Remarks
Do not keep it after destroy(): the game frees the object behind it.
Inherited from
Accessors
elapsed
Get Signature
get elapsed():
number
Defined in: handles/timer.ts:37
Gets the time since the timer last started.
Native
Bug
After resume, it counts only the time since the resume.
Returns
number
The elapsed time, in seconds.
id
Get Signature
get id():
number
Defined in: handles/handle.ts:148
Gets the game's numeric id of the Handle.
Remarks
Ids are not recycled immediately when the object is destroyed (a new
Handle created right after gets the next id), and they are allocated
deterministically from map start. An id is never data: key a collection
on the Handle (or use HandleMap and HandleSet), never on its id.
Native
Returns
number
The id, unique among the live Handles.
Inherited from
remaining
Get Signature
get remaining():
number
Defined in: handles/timer.ts:48
Gets the time left before the timer expires.
Native
Bug
The value can be wrong for a timer that was paused and later resumed: http://www.wc3c.net/showthread.php?t=95756.
Returns
number
The remaining time, in seconds.
timeout
Get Signature
get timeout():
number
Defined in: handles/timer.ts:57
Gets the timeout the timer was last started with.
Native
Returns
number
The timeout, in seconds.
Methods
destroy()
destroy():
void
Defined in: handles/timer.ts:72
Destroys the Timer through its Native.
Returns
void
Remarks
In Dev mode the destroyed Wrapper becomes a tombstone: any later access,
a second destroy() included, raises
reforged-ts: used after destroy: <Class>#<id>, and
Reforged.debug.report() counts it destroyed.
Example
The handles a feature owns, destroyed when it ends
// A shrine that stands for 60 seconds, with everything it shows. Its
// handles belong to it alone: its end destroys each of them once, on every
// client, and drops the object that held them, so no reference survives.
// Any later use of a destroyed Wrapper raises in Dev mode
// (`reforged-ts: used after destroy: <Class>#<id>`); without Dev mode it
// reaches a Handle the game has freed.
import {
Effect,
FogModifier,
Image,
ImageType,
Init,
MapPlayer,
Rectangle,
Region,
TextTag,
Timer,
Trigger,
tsGlobals,
Ubersplat,
Unit,
WeatherEffect,
} from "reforged-ts";
interface Shrine {
readonly area: Rectangle;
readonly region: Region;
readonly trigger: Trigger;
readonly timer: Timer;
readonly glow: Effect;
readonly label: TextTag;
readonly circle: Image;
readonly splat: Ubersplat;
readonly vision: FogModifier;
readonly rain: WeatherEffect;
}
let shrine: Shrine | undefined;
/** Ends the shrine: every handle it owns is destroyed, then forgotten. */
export function endShrine(): void {
if (shrine === undefined) {
return;
}
const { area, region, trigger, timer, glow, label } = shrine;
const { circle, splat, vision, rain } = shrine;
shrine = undefined;
trigger.destroy();
region.destroy();
rain.destroy();
area.destroy();
glow.destroy();
label.destroy();
circle.destroy();
splat.destroy();
vision.destroy();
timer.destroy();
}
/** Raises a shrine at (x, y) for `owner`, healing the heroes who enter. */
export function raiseShrine(owner: MapPlayer, x: number, y: number): void {
endShrine();
const area = Rectangle.create(x - 256, y - 256, x + 256, y + 256);
const region = Region.create();
region.addRect(area);
const trigger = Trigger.create().registerEnterRegion(region, () => {
return Unit.fromFilter()?.isHero() === true;
});
trigger.addAction(() => {
const hero = Unit.fromEntering();
if (hero !== undefined) {
hero.life = hero.maxLife;
}
});
const rain = WeatherEffect.create(area, FourCC("RAlr"));
rain.enable(true);
const label = TextTag.create();
label.setText("Shrine", 12, true);
label.setPos(x, y, 128);
const circle = Image.create(
"ReplaceableTextures\\Selection\\SpellAreaOfEffect.blp",
512,
512,
0,
x - 256,
y - 256,
0,
0,
0,
0,
ImageType.Indicator,
);
circle.setRender(true);
const splat = Ubersplat.create(x, y, "HMED", 255, 255, 255, 255, true, true);
splat.show(true);
const vision = FogModifier.create(
owner,
FOG_OF_WAR_VISIBLE,
x,
y,
512,
true,
false,
);
vision.start();
shrine = {
area,
region,
trigger,
timer: Timer.create().start(60, false, endShrine),
glow: Effect.create(
"Abilities\\Spells\\Human\\HolyBolt\\HolyBoltSpecialArt.mdl",
x,
y,
),
label,
circle,
splat,
vision,
rain,
};
}
Init.onGameStart(() => {
raiseShrine(tsGlobals.Players[0], 0, 0);
});
Native
pause()
pause():
Timer
Defined in: handles/timer.ts:85
Stops the countdown where it is; resume continues it.
Returns
Timer
This Timer, for chaining.
Native
Bug
The game clears the periodic flag: a periodic Timer paused then
resumed runs its remaining time and one more timeout, then stops. Start it
again with start to keep it periodic.
resume()
resume():
Timer
Defined in: handles/timer.ts:96
Continues a paused countdown from where pause stopped it; a running
Timer is left as it is.
Returns
Timer
This Timer, for chaining.
Native
start()
start(
timeout,periodic,handler):Timer
Defined in: handles/timer.ts:117
Starts the Timer; each expiry runs handler with this Timer.
Parameters
timeout
number
The time to each expiry, in seconds.
periodic
boolean
Whether the Timer starts again after each expiry;
false runs the handler once.
handler
(timer) => void
The function run at each expiry, given this Timer.
Returns
Timer
This Timer, for chaining.
Remarks
In Dev mode the handler runs under pcall: a failure is shown on
screen and printed as
reforged-ts: Timer#<id> Timer.start failed: <error>, once per distinct
message (repeats are counted in Reforged.debug.report()), and the game
thread survives it. The mode is the one in force when start is called.
With Dev mode off the handler runs unprotected, as the game runs any
function.
Native
after()
staticafter(timeout,handler):void
Defined in: handles/timer.ts:141
Runs handler once after timeout seconds, on a Timer created for it and
destroyed after the handler returns or throws (the error still
propagates). Nothing is owned, so nothing is returned: a one-shot that can
be cancelled is Timer.create().start(timeout, false, handler).
Parameters
timeout
number
The delay, in seconds.
handler
() => void
The function to run once the delay is over.
Returns
void
Remarks
In Dev mode the handler is protected as start's is, and its
failure is reported as Timer#<id> Timer.after; the Timer is destroyed
first.
Throws
In Dev mode, when called before the globals Init stage or inside
MapPlayer.runLocal, as create does.
Native
Native
Native
create()
staticcreate():Timer
Defined in: handles/timer.ts:27
Creates a stopped timer; start sets it running.
Returns
Timer
The new timer.
Throws
In Dev mode, when called before the globals Init stage or inside
MapPlayer.runLocal. The game always returns a timer, so the creation
message reforged-ts: failed to create Timer is not expected.
Native
every()
staticevery(interval,handler):Timer
Defined in: handles/timer.ts:166
Runs handler every interval seconds with the Timer, which the caller
owns: pause stops it, destroy ends it.
Parameters
interval
number
The time between two runs, in seconds.
handler
(timer) => void
The function run at each expiry, given the Timer.
Returns
Timer
The running Timer.
Remarks
In Dev mode the handler is protected as start's is, and its
failure is reported as Timer#<id> Timer.every: a handler failing on
every tick is reported once and counted after that.
Throws
In Dev mode, when called before the globals Init stage or inside
MapPlayer.runLocal, as create does.
Native
Native
fromExpired()
staticfromExpired():Timer|undefined
Defined in: handles/timer.ts:202
Gets the Timer whose expiry is running.
Returns
Timer | undefined
The expired Timer, or undefined outside a Timer's expiry.
Remarks
A handler receives its Timer; this lookup stays for parity with the Natives.
Native
fromHandle()
staticfromHandle<C>(this,handle):C|undefined
Defined in: handles/handle.ts:195
Gets the Wrapper for handle, making it on first use. The same Handle
always gives the same object; when the object cached for it is of a less
specific class than the one asked for (a Timer cached,
MyTimer.fromHandle asked), a new object of the class asked for replaces
it. Unit.fromHandle(h) is typed Unit | undefined.
Type Parameters
C
C extends Handle<handle>
The Wrapper of the class it is called on.
Parameters
this
WrapperClass<C>
handle
C["handle"] | undefined
A Handle of the class's Native type.
Returns
C | undefined
The Wrapper, or undefined when handle is undefined.
Remarks
It creates no Handle, so none of the creation Guards of Dev mode apply: wrap a Handle that Native code outside the library returned.