Action class | action.t[22], english.t[5389], objtime.t[173], sysrules.t[340]

The library doesn't yet provide any support for actions that take three objects (TIAActions, as they might hypothetically be called), but since the Mercury parser does we provide a number of hooks that other code could use. To this end we need to define the properties a TIAAction might use so the compiler recognizes them.

Modified in english.t[5389]:
Language-specific modifications to Action classes principally to enable the construction of implicit action announcements.

Modified in objtime.t[173]:
Modifications to the Action class for use with the OBJTIME EXTENSION. The purpose of these modifications is to advance the game clock each turn.

`class Action : ReplaceRedirector`

Superclass Tree (in declaration order)

`Action`
`ReplaceRedirector`
`Redirector`
`object`

Subclass Tree

`Action`
`IAction`
`LiteralAction`
`MiscConvAction`
`NumericAction`
`SystemAction`
`FileOpAction`
`TopicAction`
`ImplicitConversationAction`
`TAction`
`LiteralTAction`
`NumericTAction`
`TIAction`
`TIAAction`
`TopicTAction`
`TravelAction`

Global Objects

`FootnotesFullAction FootnotesMediumAction FootnotesOffAction Record RecordEvents RecordEventsString RecordString Replay ReplayString RestoreString Save SaveString ScriptOn ScriptString`

Summary of Properties

`actionFailed advanceOnFailure againRepeatsParse allowAll extraMessageParams failCheckMsg failedActionCountsAsTurn implicitTimeTaken includeInUndo isConversational isImplicit isRepeatable oldRoom parentAction parentAllowAll preCond redirectParent reportImplicitActions scopeList spellingPriority synthParamID timeTaken turnsTaken unhides verifyObj wasIlluminated`

``

``

Summary of Methods

`acknowledgeNotifyStatus addExtraScopeItems addImplicitTime advanceTime afterAction announceObject beforeAction buildImplicitActionAnnouncement buildScopeList checkAction checkActionPreconditions commandNotPresent exec execAction execCycle execGroup getAll getAllUnhidden getMessageParam implicitAnnouncement reportAction scoreObjects setMessageParam setMessageParams spPrefix spSuffix synthMessageParam turnSequence verify verifyObjRole wrapObjectsNP`

Inherited from `ReplaceRedirector` :
`redirect`

Inherited from `Redirector` :
`doInstead doNested doOtherAction`

Properties

`actionFailed` | `action.t[29]`

Flag; should this action be considered a failure? This should be reset to true at the start of the action processing cycle but can be tested later to prevent, e.g., inappropriate reporting.

`advanceOnFailure` | `objtime.t[190]`

Flag: should the game time be advanced if this action fails? By default we allow it to advance, but this can be overridden to nil for actions that should take no time if they're not carried out. [OBJTIME EXTENSION]

`againRepeatsParse` | `action.t[387]`

If an AGAIN command is used with this command, should the command be reparsed from scratch (because it might involve a different object) or not (because it should act on the same objects). We generally set this to true for actions it wouldn't normally make sense to repeat on the same object straight away. Since this applies to the majority of actions, we make this the default.

`allowAll` | `action.t[949]`

Can ALL be used with this action? By default we take our value from gameMain.allVerbsAllowAll, though basic inventory-handling actions in the library will override this. This property is really only relevant on TAction and its descendents, but we define it here just to make sure no cases are missed.

`extraMessageParams` | `action.t[760]`

Extra message parameters. If a message processor wants to add special message parameters of its own, we'll create a lookup table for the extra parameters. Message processors might want to add their own special parameters to allow referring to objects other than the main objects of the command.

`failCheckMsg` | `action.t[965]`

The message to display if an action fails at the check stage (via an exit macro) without any other explanatory text being displayed.

`failedActionCountsAsTurn` | `action.t[579]`

Flag, do we want an action that fails at the verify stage to count as a turn (in other words, if an action fails at the verify stage, do we want to advance the turn counter,excecute daemons, and do all the other turn sequence stuff)? By default we do, since this has long been the standard behaviour, but game code can override this to nil either globally on the Action class on on individual actions to cause failure at the verify stage to abort the remainder of the turn sequence.

`implicitTimeTaken` | `objtime.t[208]`

The number of seconds to carry out this action as an implicit action. By default we don't take any, since the normal convention seems to be to count implicit actions as part of the main action, but this could be overridden to be, say, the same as timeTaken if zero-time implicit actions were felt to give an unfair advantage to timed puzzles. [OBJTIME EXTENSION]

`includeInUndo` | `action.t[365]`

Can this action be Undone? By default most actions can.

`isConversational` | `action.t[368]`

Flag: is this a conversational action?

`isImplicit` | `action.t[362]`

Flag: is this an implicit action? By default it isn't.

`isRepeatable` | `action.t[376]`

Is this action repeatable (with an AGAIN command)? Most actions are so the default is true but subclasses can override to exclude actions (such as certain system actions) that it would make no sense to repeat.

`oldRoom` | `action.t[136]`

The room the actor was in when the action started

`parentAction` | `action.t[406]`

Do we have a parent action, and if so what is it? The parent action would be the action that's using us as an implicit action or nested action.

`parentAllowAll` | `action.t[958]`

Does the command from which we've been redirected allow ALL?

`preCond` | `action.t[146]`

A list of any PreConditions that apply to this action as a whole, as opposed to any of its objects. This is most likely to be relevant to an IAction.

`redirectParent` | `action.t[955]`

If we've been redirected here from another action, store a reference to that action.

`reportImplicitActions` | `english.t[5418]`

Flag - do we want to show implicit action reports for this action? By default we do.

`scopeList` | `action.t[937]`

Our currently cached list of items in scope for this action.

`spellingPriority` | `action.t[940]`

Used by Mercury's spelling corrector code.

`synthParamID` | `action.t[751]`

synthesized message object parameter serial number

`timeTaken` | `objtime.t[198]`

The number of seconds it takes to carry out this action. By default we assume every action takes one minute, but this can be overridden either globally on the Action class or individually on each actiom. [OBJTIME EXTENSION]

`turnsTaken` | `action.t[359]`

The number of turns this action is counted as taking. Normally, this will be 1.

`unhides` | `action.t[987]`

Flag: is this an action that acts on an object even if it is hidden; normally this will only apply to debugging actions.

`verifyObj` | `action.t[664]`

The object currently being verified

`wasIlluminated` | `action.t[139]`

Flag to indicate whether the actor's location started out illuminated

Methods

`acknowledgeNotifyStatus (stat)` | `action.t[977]`

acknowledge a change in the score notification status

`addExtraScopeItems (role?)` | `action.t[931]`

Add extra scope items if this action needs a wider definition of scope than normal. By default we simply allow the current actor's current location to add additional items to scope if it wishes to.

`addImplicitTime ( )` | `action.t[993], objtime.t[214]`

This does nothing in the main library but is provided as a hook for the objtime extension to use to add to the time taken by implicit actions.

Modified in objtime.t[214]:
Add our implicitTimeTaken to the total time taken for the turn. [OBJTIME EXTENSION]

`advanceTime ( )` | `action.t[999], objtime.t[176]`

Advance the game clock time. This does nothing in the main library but is provided as a hook for the objtime extension to use.

Modified in objtime.t[176]:
Advance the notional game time [OBJTIME EXTENSION]

`afterAction ( )` | `action.t[262], sysrules.t[352]`

Carry out the post-action processing. This first checks to see if there's been a change in illumination. If there has we either show a room description (if the actor's location is now lit) or announce the onset of darkness. We then call the after action notifications first on the actor's current room and then on every object in scope.

Note that afterAction() is called from the current Command object.

Modified in sysrules.t[352]:
Carry out the post-action processing. This first checks to see if there's been a change in illumination. If there has we either show a room description (if the actor's location is now lit) or announce the onset of darkness. We then call the after action notifications first on the actor's current room and then on every object in scope.

Note that afterAction() is called from the current Command object. [MODIFIED FOR SYSRULES EXTENSION]

`announceObject (obj)` | `english.t[5538]`

Announce an object (for use to introduce a report on what an action does to particular object when it's one of a number of objects the actions is acting upon)

`beforeAction ( )` | `action.t[209], sysrules.t[377]`

Return our overall check result.

Modified in sysrules.t[377]:
[MODIFIED FOR SYSRULES EXTENSION] Use the beforeRules RuleBook to carry out the before action handling.

`buildImplicitActionAnnouncement (success, clearReports, =, true)` | `english.t[5427]`

Construct the announcement of an implicit action according to whether the implict action succeeds (success = true) or fails (success = nil)

[Required]

`buildScopeList (whichRole, =, DirectObject)` | `action.t[915]`

Build the scope list for this action.

`checkAction ( )` | `action.t[46]`

The checkAction() method calls the check routines on the objects involved in the command (where there are objects). Subclasses such as TAction and TIAction need to override this to carry out the appropriate handling.

`checkActionPreconditions ( )` | `action.t[148]`

no description available

`commandNotPresent ( )` | `action.t[969]`

optional command is not supported in this game

`exec (cmd)` | `action.t[53]`

The main routine for handling an action. This is the method called by the command object; the cmd parameter gives the calling Command object.

`execAction (cmd)` | `action.t[131]`

The main action handler. Subclasses must override.

`execCycle (cmd)` | `action.t[88]`

The action-processing cycle carries out the before action notifications, then executes the action. This needs to be overridden on various subclasses since the beforeAction notifications can occur at different points in different kinds of action.

`execGroup (cmd)` | `action.t[38]`

The execGroup() method is called by the current Command object before it calls the action on individual objects, to allow processing of the group of objects as a whole. By default we do nothing here in the library.

`getAll (cmd, role)` | `action.t[770]`

Get a list of all the objects that this action should act on if the player typed ALL for role (DirectObject, IndirectObject, or perhaps in some future version of the library, AccessoryObject. This is the method that can be overridden on subclasses to give action-specific definitions of ALL.

`getAllUnhidden (cmd, role)` | `action.t[784]`

Get a list of all the objects this action will act on if the player types ALL for role (DirectObject or IndirectObject). This is the method actually called by the Parser. We first obtain the list of objects returned by getAll() and then filter out any objects for which hideFromAll(action) is true for this action. Subclasses should normally override getAll() rather than this method.

`getMessageParam (objName)` | `action.t[672]`

Get a message parameter object for the action. Each action subclass defines this to return its objects according to its own classifications. The default action has no objects, but recognizes 'actor' as the current command's actor.

`implicitAnnouncement (success)` | `english.t[5520]`

Return a string giving the implicit action announcement for the current action according to whether it's a success (e.g. "taking the spoon") or a failure (e.g. "trying to take the spoon"). We make this a separate method to make it a little easier for game code to customize implicit action announcements.

A return value of nil will suppress the implicit action report for this action altogeher.

`reportAction ( )` | `action.t[398]`

Report on the action. This is only relevant where the action has more or one objects, so TAction must override. This is called from the current Command object once all the objects have been acted on (in a case where multiple direct objects have been specified, as in TAKE ALL or TAKE RED BALL AND GREEN PEN). This allows the report routine to summarize the action for all the objects acted upon instead of displaying an individual report for each one.

`scoreObjects (cmd, role, lst)` | `action.t[830]`

Score a set of objects in a given noun role in the action, in order to resolve an ambiguous command. Our job, in brief, is to READ THE PLAYER'S MIND: we want to figure out which object or objects the player is actually referring to when their words are ambiguous.

'cmd' is the Command object describing the command. The various object lists (dobjs, iobjs, accs) have been filled in with the in-scope objects that match the noun phrase, but these haven't been disambiguated yet, so there might be more objects listed than will actually be used in the final command.

'role' tells us the noun phrase role that we're scoring (DirectObject, IndirectObject, AccessoryObject, TopicRole, LiteralRole).

'lst' is the match list. This is a Vector containing NPMatch objects. There's one NPMatch for each object that we're considering as a match for the player's noun phrase.

For each item in the match list, we must set the NPMatch object's 'score' property to a number indicating how likely we think it is that the player is referring to this object. The higher the score, the more likely we think it is. The score value is purely relative - the caller will pick the object or objects with the highest score.

We run through the verify routine for each object, which in turn runs through the preconditions of that object. We take the returned verify score to be the score for the object (or its replacement if remapping took place).

Next, we do any verb-specific adjustments via self.actionScore().

Finally, we call each object's scoreObject() routine to give the object a chance to make any adjustments for special affinities (or aversions).

`setMessageParam (objName, obj)` | `action.t[708]`

Define an extra message-specific parameter. Message processors can use this to add their own special parameters, so that they can refer to parameters that aren't involved directly in the command. For example, a message for "take <dobj>" might want to refer to the object containing the direct object.

`setMessageParams ([lst])` | `action.t[725]`

For convenience, this method allows setting any number of name/value pairs for message parameters.

`spPrefix (str)` | `english.t[5530]`

add a space prefix/suffix to a string if the string is non-empty

`spSuffix (str)` | `english.t[5531]`

no description available

`synthMessageParam (obj)` | `action.t[736]`

Synthesize a global message parameter name for the given object. We'll store the association and return the synthesized name.

`turnSequence ( )` | `action.t[327], sysrules.t[406]`

The turnSequence() method is called from the current Command object. It first executes any current daemons (apart from any PromptDaemons) and then advances the turn counter. We define this on the Action class principally to make it simple for certain kinds of Action such as SystemActions to do nothing here (since they don't count as actions within the game world).

Modified in sysrules.t[406]:
[MODIFIED FOR SYSRULES EXTENSION] Use the turnEnd RuleBook to carry out the end-of-turn processing.

`verify (obj, role)` | `action.t[415]`

Carry out the verification stage for this object in this role, and carry out any remapping needed. This needs to be defined on Action since there might be verification of the ActorRole.

`verifyObjRole (obj, role)` | `action.t[589]`

Run the verify routine on the current object in the current role to see whether it will allow the action. If it won't, display any pending implicit action announcements, then display the message explaining why the action is disallowed, and finally return nil to tell our caller to halt the action. If the verify stage does allow the action to go ahead, return true to tell our caller that this routine has no objection.

`wrapObjectsNP (lst)` | `action.t[902]`

Wraps a list of objects in NPMatch objects so they can be run through the scoreObjects method.

Adv3Lite Library Reference Manual
Generated on 25/04/2024 from adv3Lite version 2.0