#charset "us-ascii"
#include "advlite.h"
/*
* EventListItem Extension
*. Version 1.1 17-Dec-2022
*. By Eric Eve based on work by John Ziegler
*/
/*
* An EventListItem is an object that can be used within an EventList but is only used when
* certain conditions are met (its isReady property evaluates to true, the game clock time is at
* or after any next firing time we have defined, and it hasn't already been used for any maximum
* number of times we care to define).
*
* EventListItems can be added to a regular EventList object by locating them within that object
* using the + notation. [EVENTLISTITEM EXTENSION]
*
*/
class EventListItem: PreinitObject
/*
* Add this EventListItem to the eventList of the EventList object with which is is to be
* associated.
*/
execute()
{
/*
* if myListObj is defined, add us to that EventList object. whichList is by default
* &eventList, but this could be changed to &firstEvents or some other custom property
*/
if(myListObj)
myListObj.(whichList) += self;
/*
* if we don't specify myListObj but we have a location, add us to our
* location.(whichList)
*/
else if(location &&
location.propDefined(whichList) &&
location.(whichList)!=nil &&
location.(whichList).ofKind(Collection))
{
location.(whichList) += self;
myListObj = location;
}
}
/*
* we usually want to add objects to a ShuffledEventList's eventList property, but
* items/subclasses could change this to be added to firstEvents or some other alternate list
* within the EventList object
*/
whichList = &eventList
/*
* The EventList object to which we are to belong. If this is left at nil, our location will
* be used.
*/
myListObj = nil
/*
* When the event list to which we've been added gets to us, it will call our doScript()
* method, so we use that to define what happens.
*/
doScript()
{
/* If we're in a position to fire, then carry out our invocation. */
if(canFire())
{
_invokeItem();
/* If we've been mixed in with an EventList class, call the inherited handling. */
if(ofKind(Script))
inherited();
}
/* Otherwise, use our fallback routine. */
else
fallBack();
}
_invokeItem()
{
invokeItem();
//keep track of how many times this item has shown
++fireCt;
//keep track of when we fired last
lastClock = gTurns;
// automatically remove if we have exceeded our maxFireCt or met our doneWhen condition
if((maxFireCt && fireCt >= maxFireCt) || doneWhen)
setDone();
/* Delay our next use until at least minInterval turns have elapsed. */
setDelay(minInterval);
/* Reset our missed turn flag to nil as we haven't missed this turn. */
missedTurn = nil;
}
/*
* Here goes the code (or a double-quoted string) that carries out what we do when we're
* invoked. Game code will need to define what should happen here.
*/
invokeItem()
{
}
/*
* This first turn on which we came up in our EventList but were unable to fire, or nil if we
* have either not missed or turn or fired on the previous occasion we could.
*/
missedTurn = nil
/*
* The method that defines what this EventListItem does if it's invoked when it's not ready to
* fire.
*/
fallBack()
{
/*
* If possible, get our myListObj to use the next item in its list, so that it behaves as
* if we werem't here. However, we need to make sure it's safe to do that without getting
* into an infinite loop, so to be on the safe side we check (1) that there's at least one
* item in the list which our myListObj could invoke (i.e. something that's not an
* EventListItem that can't fire) and (2) that myListOnj is not a StopEventList that's
* reached its end, which might then repeatedly try to invoke us.
*/
if(myListObj.(whichList).indexWhich({x: !(x.ofKind(EventListItem) && !x.canFire())})
&& !(myListObj.ofKind(StopEventList)&& myListObj.curScriptState >= eventListLen))
myListObj.doScript();
/* Otherwise, use our fallBackResponse */
else
fallBackResponse();
/*
* Unless we're done or we've already noted a missed turn, note that we missed our chance
* to fire with our own response this turn.
*/
if(!isDone && missedTurn == nil)
missedTurn = gTurns;
}
/*
* The response to use if all else fails, that is if there we cannot fire ourselves and there
* is no non-EventListItem (which could be used in our place) in the eventList to which we
* belong. This could, for exmple, display another message or it could just do nothing, which
* is the default. We only need to supply something here if we belong to an EventList that
* should display something every turn, for example as a response to a DefaultTopic or else if
* we are or may be the final item in a StopEventList.
*/
fallBackResponse() { }
/*
* Is this EventListItem ready to fire? Note that this is addition to its not being done and
* having reached its ready time.
*/
isReady = true
/*
* Can this EventListItem item fire? By default it can if its isReady condition is true and it
* is not already done (isDone != true) and the turn count exceeds its ready time.
*/
canFire()
{
return isReady && !isDone && gTurns >= readyTime;
}
/* Have we finished with this EventListItem? */
isDone = nil
/* Set this EventListItem as having been done */
setDone()
{
isDone = true;
}
/* The number of times this EventListItem has fired. */
fireCt = 0
/*
* Flag: can this EventListItem be removed from its eventList once isDone = true? By default
* it can, but note that this flag only has any effect when our EventList's resetEachCycle
* property is true. We might want to set this to nil if isDone might become nil again on this
* EventListItem, to avoid it being cleared out of its eventList.
*/
canRemoveWhenDone = true
/*
* The maximum number of times we want this EventListItem to fire. The default value of nil
* means that this EventListItem can fire an unlimited unmber of times. For an EventListItem
* that fires only once, set maxFireCt to 1 or use the ELI1 subclass.
*/
maxFireCt = nil
/*
* An alternative condition (which could be defined as a method) which, if true, causes this
* EventListItem to be finished with (set to isDone = true). Note that isDone will be set to
* try either if this EventListItem exceeds its maaFireCt or if its doneWhen method/property
* evaluates to true.
*/
doneWhen = nil
/* The last turn on which this EventListItem fired */
lastClock = 0
/*
* The turn count that must be reached before we're ready to fire. By default this is 0, but
* game code can use this or set the setDelay() method to set/reset it.
*/
readyTime = 0
/* The minimum interval (in number of turns) between repeated occurrences of this item. */
minInterval = 0
/*
* Set the number of turns until this EventListItem can be used again. This could, for
* example, be called from invokeItem() to set a minimum interval before this EventListItem is
* repeated.
*/
setDelay(turns)
{
readyTime = gTurns + turns;
return self;
}
/* Get the actor with which we're associated if we have one. */
getActor
{
local obj = [location, myListObj].valWhich({x:x && (x.ofKind(ActorState) ||
x.ofKind(Actor) || x.ofKind(AgendaItem)) });
if(obj)
return obj.getActor;
else
return nil;
}
/*
* Has this EventListItem been underused? By default it has if it hasn't been used at all or
* it missed out the last time it was called by not being ready, but game code can override if
* it wants to employ some other condition, such as the number of times we've been used in
* relation to other items in our listObj. The purpose of this is to allow RandomFiringScripts
* to prioritize underused EventListItems once they become ready to fire.
*/
underused()
{
/*
* By default we're underused if we've we've missed a turn on which we would have fired
* had we been ready to, but game code can override this to some other condition if
* desired, such as testing whether fireCt == 0
*/
return (missedTurn != nil);
}
/*
* Add this EventListItem to the whichList list of myListObj_. If specificied, whichList must
* be supplied as a property, and otherwise defaults to &eventList. A minimium interval
* between firings of this EventList item can optionally be specified in the minInterval_
* parameter, but there is no need to do this if this EventList already defines its own
* minInterval or doesn't require one.
*/
addToList(myListObj_, whichList_ = &eventList, minInterval_?)
{
/* Store our parameters in the appropriate properties. */
myListObj = myListObj_;
whichList = whichList_;
if(minInterval_)
minInterval = minInterval_;
/* Get our list object to add us to its appropriate list property. */
myListObj.addItem(self, whichList);
}
;
/*
* Short form EventListItem class names for the convenience of game authors who want to save
* typing.
*/
class ELI: EventListItem;
/* A one-off EventListItem */
class ELI1: EventListItem
maxFireCt = 1
;
modify EventList
/*
* Game code can call this method to remove all EventListItems that have been finished with
* (isDone = true) from the eventList of this EventList. This probably isn't necessary unless
* there are likely to be a large number of such items slowing down execution.
*/
resetList()
{
/*
* Reduce our eventList to exclude items that are EventListItems for which isDone is true
* and the canRemoveWhenDone flag is true.
*/
self.eventList = self.eventList.subset({x: !(objOfKind(x, EventListItem) && x.isDone &&
x.canRemoveWhenDone)});
/* Recache our eventList's new length. */
eventListLen = eventList.length();
}
/*
* Flag, do we want to reset the list each time we've run through all our items? By default we
* don't, but this might ba en appropriate place to call resetList() if we do want to call it.
* Note that this is in any case irrelevant on the base EventList class but may be relevant on
* some of its subclaases (CyclicEventList, RandomEventList and ShuffledEventList).
*/
resetEachCycle = nil
/*
* Add an item to prop (usually eventList) property of this EventList, where prop should be
* supplied as a property pointer,
*/
addItem(item, prop)
{
/* Add the item to the specified list. */
self.(prop) += item;
/* Chache our new eventList length. */
eventListLen = eventList.length;
}
;
modify CyclicEventList
advanceState()
{
/*
* If we want to reset our eventList each cycle to clear out any spent EventListItems and
* our current script state has reache our eventList's length (so that we're at the end of
* a cycle), then call our resetList() method.
*/
if(resetEachCycle && curScriptState >= eventListLen)
resetList();
/* Carry out the inherited handling */
inherited();
}
;
/* Mofiications to ShuffledEventList for EventListItem extension */
modify ShuffledEventList
/*
* For the EventListItem extenstion we modify this method so that it first chooses any as yet
* unused EventListItem from our eventList that's now ready to fire. If none is found, we use
* the inherited behaviour to select the next item indicated by our shuffledList_ .
*/
getNextRandom()
{
/*
* If we want to clear up isDone items and we have a shuffledList_ and that list has no
* more values available, then reset our list to remove the isDone items.
*/
if(resetEachCycle && shuffledList_ && shuffledList_.valuesAvail == 0)
resetList();
/*
* If we have an underused EventListItem that's ready to fire, choose that.
*/
local idx = underusedReadyELIidx();
/*
* If we found a suitable value and idx is not nil, return idx. Otherwise use the
* inherited value
*/
return idx ?? inherited();
}
/*
* Reset our eventList to clear out EventListItems that are done with (isDone = true). This is
* not called from any library code by default, but can be called from game code if game
* authors are worried about an accumulation of too many spent EventListItems in any given
* eventList. For many games, this probably won't be necessary.
*
* One potentially good place to call this from as at the end of each iteration of a
* ShuffledEventList, when the items are about to be reshuffled in any case. You can make this
* happen by setting the resetOnReshuffle property to true,
*/
resetList()
{
/* Carry out the inherited handling */
inherited();
/*
* recreate our shuffled integer list, since the existing one may index items that no
* lomger exist in our eventList.
*/
shuffledList_ = new ShuffledIntegerList(1, eventListLen);
/* apply our suppressRepeats option to the shuffled list */
shuffledList_.suppressRepeats = suppressRepeats;
}
addItem(item, prop)
{
/* Carry out the inherited handling */
inherited(item, prop);
/* Reset our list to include the item we've just added and clear out any spent ones. */
resetList();
}
;
modify RandomEventList
/*
* Get the next random state. By default, we simply return a number from 1 to the number of
* entries in our event list. This is a separate method to allow subclasses to customize the
* way the random number is selected. However, if we have an unused EventListItem that's ready
* to fire, we select that instead, to make sure it gets a look-in at the earliest possible
* opportunity.
*/
getNextRandom()
{
/*
* For a RandomEventList we regard a 'cycle' as being the firing of the number of items in
* the eventList (regardless of whether each individual item has been fired). So we
* increment our fireCt each time we're called, and then reset it to zero once it reaches
* our eventLiatLen. Then, if thie RandeomEventList wants to resetEachCycle, we clear out
* any spent EventListItems.
*/
if(++fireCt >= eventListLen)
{
/* Reset our fireCt to zero */
fireCt = 0;
/*
* Call resetList() to clear out any spent EventListItems if we want to reset each
* cycle.
*/
if(resetEachCycle)
resetList();
}
/*
* If we have an underused EventListItem that's ready to fire, choose that
*/
local idx = underusedReadyELIidx();
/*
* If we found a suitable value and idx is not nil, return idx. Otherwise use the
* inherited value
*/
return idx ?? inherited();
}
/* The number of times we have fired on this 'cycle '*/
fireCt = 0
;
modify RandomFiringScript
/*
* Return the index within our eventList of any as yet unused EventListItem that's ready to
* fire. This is principally for the use of our RandomEventList and ShuffledEventList
* subclasses.
*/
underusedReadyELIidx()
{
/* Extract a subset list of EventListItems that can fire and are underused. */
local lst = eventList.subset({x: objOfKind(x, EventListItem) && x.canFire()
&& x.missedTurn && x.underused()});
/* If the list is empty, we have no underused EventListItem ready to fire, so return nil. */
if(lst.length < 1)
return nil;
/* Sort the list in ascendcing order of their missedTurns. */
lst = lst.sort({a, b: a.missedTurn - b.missedTurn});
/*
* Return the index of the first element in the list, which will be the one that missed
* its turn longest ago.
*/
return eventList.indexOf(lst[1]);
}
;
Adv3Lite Library Reference Manual
Generated on 01/03/2024 from adv3Lite version 1.6.2