#charset "us-ascii"
#include "advlite.h"
/*
* SUBTIME EXTENSION
*
* Copyright 2003, 2006 Michael J. Roberts
*
* Adapted for use with adv3Lite by Eric Eve; the changes include using the
* Date class rather than the custom format for storing dates and times used
* in MJR's original version.
*
* "Subjective Time" module. This implements a form of in-game time-keeping
* that attempts to mimic the player's subjective experience of time passing
* in the scenario while still allowing for occasional, reasonably precise
* time readings, such as from a wristwatch in the game world.
*
*
*/
property gameStartTime;
/*
* The clockManager object is used to keep track of subjective time. In this
* version we store dates and times internally as Date objects, although we
* recognize date/times in the form [d, h, m] defined on ClockEvents.
* [DEFINED IN SUBTIME EXTENSION]
*/
clockManager: PreinitObject
/*
* Get the current game-clock time. This returns date/time as a Date
* object.
*
* Remember that our time-keeping scheme is a sort of "Schrodinger's
* clock" [see footnote 1]. Between time checks, the game time clock is
* in a vague, fuzzy state, drifting along at an indeterminate pace from
* the most recent check. When this method is called, though, the clock
* manager is forced to commit to a particular time, because we have to
* give a specific answer to the question we're being asked ("what time is
* it?"). As in quantum mechanics, then, the act of observation affects
* the quantity being observed. Therefore, you should avoid calling this
* routine unnecessarily; call it only when you actually have to tell the
* player what time it is - and don't tell the player what time it is
* unless they ask, or there's some other good reason.
*
* If you want a string-formatted version of the time (as in '9:05pm'),
* you can call checkTimeFmt().
*/
checkTime()
{
local turns;
local mm;
local sdmm;
/*
* Determine how many turns it's been since we last committed to
* a specific wall-clock time. This will give us the
* psychological "scale" of the amount of elapsed wall-clock the
* user might expect.
*/
turns = libGlobal.totalTurns - turnLastCommitted;
/*
* start with the base scaling factor - this is the number of
* minutes of game time we impute to a hundred turns, in the
* absence of the constraint of running up against the next event
*/
mm = (turns * baseScaleFactor) / 100;
/*
* If the base scaled time would take us within sdmm of the next event
* time, slow the clock down from our base scaling factor so that we
* always leave ourselves room to advance the clock further on the
* next check. Reduce the passage of time in proportion to our
* reduced window - so if we have only 60 minutes left, advance time
* at half the normal pace.
*/
if (nextTime != nil)
{
/*
* In Mike Roberts's version of subtime, the clock is slowed down
* if the base scaled time would take us within two hours of the
* next event time, but this may be inappropriate if the game is
* working to a much shorter or longer timescale. So we instead
* compute the time at which slowing down should occur in a
* separate method to make it easy for game code to override it.
* By default, the slow-down time will be half-way between the
* previous event and the next one.
*/
sdmm = slowDownTime();
/* get the minutes between now and the next scheduled event */
local delta = (nextTime - curTime) * 1440;
/* check to see if the raw increment would leave under sdmm minutes */
if (delta - mm < sdmm)
{
/*
* The raw time increment would leave us under sdmm minutes
* away. If we have under sdmm to go before the
* next event, scale down the rate of time in proportion
* to our share under sdmm. (Note that we might
* have more than sdmm to go and still be here,
* because the raw adjusted time leaves under sdmm minutes.)
*/
if (delta < sdmm)
mm = (mm * delta) / sdmm;
/*
* In any case, cap it at half the remaining time, to
* ensure that we won't ever make it to the next event
* time until the next event occurs.
*/
if (mm > delta / 2)
mm = delta / 2;
}
}
/*
* Otherwise, if we have no further events, take the time from the
* timeManager, if it exists.
*/
else if(defined(timeManager))
{
curTime = timeManager.currentTime;
return curTime;
}
/*
* If our calculation has left us with no passage of time, simply
* return the current time unchanged, and do not treat this as a
* commit point. We don't consider this a commit point because
* we treat it as not even checking again - it's effectively just
* a repeat of the last check, since it's still the same time.
* This ensures that we won't freeze the clock for good due to
* rounding - enough additional turns will eventually accumulate
* to nudge the clock forward.
*/
if (mm == 0)
return curTime;
/* add the minutes to the current time */
curTime = curTime.addInterval([0, 0, 0, 0, mm]);
/* the current turn is now the last commit point */
turnLastCommitted = gTurns;
/*
* If the timeManager exists and its time is earlier than the time we
* just calculated, use the timeManager's time.
*/
if(defined(timeManager) && timeManager.currentTime < curTime)
curTime = timeManager.currentTime;
/* If the timeManager exists, synchronize its time with ours. */
syncTime(curTime);
/* return the new time */
return curTime;
}
/*
* Compute the time remaining until the next event at which we start to
* slow down the clock. By default we make this half the time from the
* previous event to the next. Game code can override if some other value
* is preferred. [SUBTIME EXTENSION]
*/
slowDownTime()
{
/*
* If we have a lastEvent, get its eventTime; otherwise assume the
* last event was at our baseDate.
*/
local lastEventTime = lastEvent == nil ? baseDate : lastEvent.eventDate;
/*
* Return half the difference between the next event time and the last
* event time.
*/
return (nextTime - lastEventTime) * 720;
}
/*
* The base scaling factor: this is the number of minutes per hundred
* turns when we have unlimited time until the next event. This number is
* pretty arbitrary, since we're depending so much on the player's
* uncertainty about just how long things take, and also because we'll
* adjust it anyway when we're running out of time before the next event.
* Even so, you might want to adjust this value up or down according to
* your sense of the pacing of your game.
*
* In Mike Roberts's implementation, the baseScaleFactor was defined as a
* constant value of 60. This is still the default value, but if there is
* a next event we take the scale factor from that event's scaleFactor so
* that we can vary the pace of time according to the spacing of events if
* we wish. [SUBTIME EXTENSION]
*/
baseScaleFactor = (nextEvent == nil ? scaleFactor : nextEvent.scaleFactor)
/*
* The scaling factor to use once we have passed the last ClockEvent; this
* is the number of minutes per hundred turns once there are no more
* ClockEvents. [SUBTIME EXTENSION]
*/
scaleFactor = 60
/*
* Get the current game-clock time, formatted into a string with the
* given format mask - see formatTime() for details on how to write a
* mask string.
*
* Note that the same cautions for checkTime() apply here - calling
* this routine commits us to a particular time, so you should call
* this routine only when you're actually ready to display a time to
* the player. [SUBTIME EXTENSION]
*/
checkTimeFmt(fmt) { return formatTime(checkTime(), fmt); }
/*
* Get a formatted version of the given wall-clock time. The time (t)
* parameter can be expressed as a list, in the same format as
* ClockEvent.eventTime: [day,hour,minute], where 'day' is 1 for the first
* day of the game, 2 for the second, and so on. Alternatively it can be
* supplied as a Date object.
*
* The format string (fmt) is specified in the same way as for the
* formatDate() method of the Date class (for which see the TADS 3 System
* Manual). [SUBTIME EXTENSION]
*/
formatTime(t, fmt)
{
/*
* If t has been supplied as a list in the [d, h ,m] format we first
* need to convert it into a Date object
*/
if(dataType(t) == TypeList)
t = eventDate(t);
return t.formatDate(fmt);
}
/* pre-initialize the clockManager [SUBTIME EXTENSION]*/
execute()
{
local vec;
/*
* If the gameMain object defines a gameStartTime, use it to set our
* baseDate.
*/
if(gameMain.propDefined(&gameStartTime))
{
local gst = gameMain.gameStartTime;
if(dataType(gst) == TypeList)
baseDate = new Date(gst[1], gst[2], gst[3]);
if(dataType(gst) == TypeObject && gst.ofKind(Date))
baseDate = gst;
}
/* build a list of all of the ClockEvent objects in the game */
vec = new Vector(10);
forEachInstance(ClockEvent, function(x) {
vec.append(x);
/*
* Fill in the ClockEvent's eventDate property with a Date object
* derived from its eventTime, unless the eventDate has already
* been supplied.
*/
if(x.eventDate == nil)
x.eventDate = eventDate(x.eventTime);
/*
* Otherwise, if a Date has been specified, use it to fill in the
* eventTime property.
*/
else
x.eventTime = getClockTime(x.eventDate);
});
/* sort the list by time */
vec.sort(SortAsc, {a, b: a.eventDate.compareTo(b.eventDate)});
/* store it */
eventList = vec.toList();
/*
* The earliest event is always the marker for the beginning of
* the game. Since it's now the start of the game, mark the
* first event in our list as reached. (The first event is
* always the earliest we find, by virtue of the sort we just
* did.)
*/
vec[1].eventReached();
/*
* If the events module is present, set up a PromptDaemon to check
* each turn whether a new ClockEvent has been reached.
*/
if(defined(eventManager))
new PromptDaemon(self, &reachCheck);
/*
* If the timeManager exists, synchronize its current start time with
* ours, if we have one.
*/
if(defined(timeManager) && lastEvent)
timeManager.currentTime = lastEventDate();
}
/*
* Receive notification from a clock event that an event has just
* occurred. (This isn't normally called directly from game code;
* instead, game code should usually call the ClockEvent object's
* eventReached() method.) [SUBTIME EXTENSION]
*/
eventReached(evt)
{
local idx;
/* find the event in our list */
idx = eventList.indexOf(evt);
/*
* Never go backwards - if events fire out of order, keep only
* the later event. (Games should generally be constructed in
* such a way that events can only fire in order to start with,
* but in case a weird case slips through, we make this extra
* test to ensure that the player doesn't see any strange
* retrograde motion on the clock.)
*/
if (lastEvent != nil && lastEvent.eventDate > evt.eventDate)
return;
/* note the current time */
curTime = evt.eventDate;
/* note the event that's just been reached */
lastEvent = evt;
/*
* if there's another event following, note the next time and the next
* event, and get the next event to calculate its scale factor.
*/
if (idx < eventList.length())
{
nextEvent = eventList[idx + 1];
nextTime = nextEvent.eventDate;
nextEvent.calcScaleFactor();
}
else
{
nextEvent = nil;
nextTime = nil;
}
/*
* we're committing to an exact wall-clock time, so remember the
* current turn counter as the last commit point
*/
turnLastCommitted = gTurns;
/* Note that the event has been reached */
evt.hasBeenReached = true;
/* If the timeManager exists, synchronize its time with ours. */
syncTime(curTime);
}
/*
* Check each turn whether another ClockEvent has been reached. Note that
* this requires the events.t module to be present to work. [SUBTIME EXTENSION]
*/
reachCheck()
{
/* Go through every ClockEvent in our eventList */
foreach(local cur in eventList)
{
/*
* If we find one that hasn't been reached before, but whose
* reachedWhen condition is now true, note that it has now been
* reached.
*/
if(!cur.hasBeenReached && cur.reachedWhen)
{
eventReached(cur);
/*
* Don't continue searching for ClockEvents on this turn; we
* don't want more than one ClockEvent to be reached at a
* time.
*/
break;
}
}
}
/*
* our list of clock events (we build this automatically during
* pre-initialization) [SUBTIME EXTENSION]
*/
eventList = nil
/* the current game clock time [SUBTIME EXTENSION] */
curTime = nil
/* the most recent event that we reached [SUBTIME EXTENSION] */
lastEvent = nil
/* the next event's game clock time [SUBTIME EXTENSION] */
nextTime = nil
/* the next event we're due to reach [SUBTIME EXTENSION] */
nextEvent = nil
/*
* The turn counter (Schedulable.gameClockTime) on the last turn
* where committed to a specific time. Each time we check the time,
* we look here to see how many turns have elapsed since the last
* time check, and we use this to choose a plausible scale for the
* wall-clock time change. [SUBTIME EXTENSION]
*/
turnLastCommitted = 0
/*
* The base date (year, month, day) our game is meant to start on,
* expressed as a Date object. Often this doesn't matter if we're only
* interested in the time of day. By default we make it Jan 1, 2000. If
* gameMain.gameStartDate is defines it will instead be taken from there.
* [SUBTIME EXTENSION]
*/
baseDate = static new Date(2000, 1, 1)
/* Return the date of t as a Date object. [SUBTIME EXTENSION] */
eventDate(t)
{
/* If t is nil, return nil */
if(t == nil)
return nil;
/* Get the date only part of the base date */
local bd = baseDate.getDate();
/* Create a Date object representing midnight on our base date */
local curDate = new Date(bd[1], bd[2], bd[3]);
/*
* Advance this date by the number of days the lastEventTime is from
* the starting time, which is usually day 1
*/
curDate = curDate.addInterval([0, 0, t[1] - 1]);
/* Extract the date part again */
curDate = curDate.getDate();
/* Return the date and time as a Date object */
return new Date(curDate[1], curDate[2], curDate[3], t[2], t[3], 0, 0);
}
/* Retutn the date and time of the last event as a Date object. [SUBTIME EXTENSION] */
lastEventDate()
{
return lastEvent ? eventDate(lastEvent.eventTime) : nil;
}
/* Get the time in our [d, h, m, s] format from a Date object. [SUBTIME EXTENSION] */
getClockTime(dat)
{
/* Get the time element of the Date object */
local t = dat.getHMS();
/* Get the number of days between the Date object and our baseDate */
local days = toInteger(dat - baseDate);
/*
* return the resultant time in [d, h, m] format
*/
return [days + 1, t[1], t[2]];
}
/* Synchronize the timeManager's time with our time, if it exists. [SUBTIME EXTENSION] */
syncTime(t)
{
if(defined(timeManager))
{
/* Set the timeManager's time to our time. */
timeManager.currentTime = t;
/*
* Try to prevent the current turn from advancing the
* timeManager's time beyond our time.
*/
takeTime(0);
}
}
;
/*
* Clock-setting plot event. This object represents a plot point that
* occurs at a particular time in the story world. Create one of these
* for each of your plot events. The Clock Manager automatically builds
* a list of all of these objects during pre-initialization, so you don't
* have to explicitly tell the clock manager about these.
*
* Whenever the story reaches one of these events, you should call the
* eventReached() method of the event object. This will set the clock
* time to the event's current time, and take note of how long we have
* until the next plot event.
* [DEFINED IN SUBTIME EXTENSION]
*/
class ClockEvent: object
/*
* The time at which this event occurs. This is expressed as a list
* with three elements: the day number, the hour (on a 24-hour
* clock), and the minute. The day number is relative to the start
* of the game - day 1 is the first day of the game. So, for
* example, to express 2:40pm on the second day of the game, you'd
* write [2,14,40]. Note that 12 AM is written as 0 (zero) on a
* 24-hour clock, so 12:05am on day 1 would be [1,0,5].
*/
eventTime = [1,0,0]
/* This is the eventTime expressed as a Date object */
eventDate = nil
/* get a formatted version of the event time */
formatTime(fmt) { return clockManager.formatTime(eventTime, fmt); }
/*
* Notify the clock manager that this event has just occurred. This
* sets the game clock to the event's time. The game code must call
* this method when our point in the plot is reached.
*/
eventReached()
{
/* notify the clock manager */
clockManager.eventReached(self);
}
/*
* This is the number of minutes per hundred turns when we have unlimited
* time until this next event. This number is pretty arbitrary, since
* we're depending so much on the player's uncertainty about just how long
* things take, and also because we'll adjust it anyway when we're running
* out of time before the next event. Even so, you might want to adjust
* this value up or down according to your sense of the pacing of your
* game.
*
* Alternatively you can define the turnsToEvent property (see below) and
* the game will calculate an appropriate scaleFactor for you.
* [SUBTIME EXTENSION]
*/
scaleFactor = 60
/*
* Optional: if specified this should contain an estimate of the number of
* turns a player is typically likely to take to get to this event from
* the previous one; the game will then calculate an appropriate
* scaleFactor. Alternatively this can be left at nil and the scaleFactor
* specified directly. [SUBTIME EXTENSION]
*/
turnsToEvent = nil
/*
* If the turnsToEvent property is not nil and the clockManager has
* recorded a previous event, calculate the scaleFactor for this event.
* [SUBTIME EXTENSION]
*/
calcScaleFactor()
{
if(turnsToEvent && clockManager.lastEvent)
{
/*
* Calculate the number of minutes between this event and the
* previous event.
*/
local delta = (eventDate - clockManager.lastEvent.eventDate) * 1440;
/*
* Calculate the scaleFactor such that 100 turns will take
* scaleFactor minutes.
*/
scaleFactor = (delta * 100)/turnsToEvent;
}
}
/*
* A condition (or a method that returns true or nil) that causes this
* event to be reached when it becomes true. This provides an alternative
* way of reaching events (instead of calling the eventReached method).
* [SUBTIME EXTENSION]
*/
reachedWhen = nil
/*
* Flag: has this event been reached? This is used internally by the
* library and shouldn't normally be changed in game code.
* [SUBTIME EXTENSION]
*/
hasBeenReached = nil
;
/* ------------------------------------------------------------------------ */
/*
* [Footnote 1]
*
* "Schrodinger's cat" is a famous thought experiment in quantum
* physics, concerning how a quantum mechanical system exists in
* multiple, mutually exclusive quantum states simultaneously until an
* observer forces the system to assume only one of the states by the
* act of observation. The thought experiment has been popularized as
* an illustration of how weird and wacky QM is, but it's interesting to
* note that Schrodinger actually devised it to expose what he saw as an
* unacceptable paradox in quantum theory.
*
* The thought experiment goes like this: a cat is locked inside a
* special box that's impervious to light, X-rays, etc., so that no one
* on the outside can see what's going on inside. The box contains,
* apart from the cat, a little radiation source and a radiation
* counter. When the counter detects a certain radioactive emission, it
* releases some poison gas, killing the cat. The radioactive emission
* is an inherently quantum mechanical, unpredictable process, and as
* such can (and must) be in a superposition of "emitted" and "not
* emitted" states until observed. Because the whole system is
* unobservable from the outside, the supposition is that everything
* inside is "entangled" with the quantum state of the radioactive
* emission, hence the cat is simultaneously living and dead until
* someone opens the box and checks. It's not just that no one knows;
* rather, the cat is actually and literally alive and dead at the same
* time.
*
* Schrodinger's point was that this superposition of the cat's states
* is a necessary consequence of the way QM was interpreted at the time
* he devised the experiment, but that it's manifestly untrue, since we
* know that cats are macroscopic objects that behave according to
* classical, deterministic physics. Hence a paradox, hence the
* interpretation of the theory must be wrong. The predominant
* interpretation of QM has since shifted a bit so that the cat would
* now count as an observer - not because it's alive or conscious or
* anything metaphysical, but simply because it's macroscopic - so the
* cat's fate is never actually entangled with the radioactive source's
* quantum state. Popular science writers have continued to talk about
* Schrodinger's cat as though it's for real, maybe to make QM seem more
* exotic to laypersons, but most physicists today wouldn't consider the
* experiment to be possible as literally stated. Physicists today
* might think of it as a valid metaphor to decribe systems where all of
* the components are on an atomic or subatomic scale, but no one today
* seriously thinks you can create an actual cat that's simultaneously
* alive and dead.
*/
Adv3Lite Library Reference Manual
Generated on 01/03/2024 from adv3Lite version 1.6.2