Debugging:Debug in Game
AdventureJS can print certain types of debugging information directly to the game display. One type of debug statement can help authors solve "you can't do that" sort of problems, while others can help point out ways to inject custom code into the game loop. Below is a list of the options, and an example of how to enable or disable them in your game file. Also see further down the page for examples of how these debug messages appear in the display. All options are disabled by default, so you only need to include the options you want to enable.
MyGame.settings.set({
debug = {
// print all options regardless of their settings
all: false,
// show explanation of player input failures
general: false,
// show when attempts are made to call [verb action hooks](/doc/BasicVerbs_ActionHooks.html)
verbaction: false,
// show when attempts are made to call [verb reaction hooks](/doc/BasicVerbs_ReactionHooks.html)
verbreaction: false,
// show when attempts are made to call [verb phase hooks](/doc/BasicVerbs_ActionHooks.html)
verbphase: false,
};
});
general statements
The general debug statements are meant to help authors debug
their games from a player's perspective. They will explain why a player is
unable to perform any given action, i.e. "you can't do that". It's
possible that an author didn't intend for that thing to be undoable, and this
can help track down what needs to be changed to make it work.
If the player used an unknown word, tried to get on a thing they're already on, tried to use a door that doesn't exist, tried to climb a thing that's not climbable, tried to take a thing that's not takeable, tried to speak to a character who's not present, tried to use a sentence structure with a verb that doesn't support it, or any of literally a thousand other things, AdventureJS will print a debug message to explain exactly why, and where to find the source code that generated the message.
See the transcript fragments below for examples. General debug statements have code numbers in the form of D1234. If you're motivated enough to edit the adventure.js source code, searching for a debug code will take you to the code block that generated the message.
Expand for general examples
In this block, D1112 tells us there is no south exit and D1124 tells us that the game's settings tell the game to print a list of exits on travel fail.
In this block, D1703 tells us that verb open found the door
locked.
In this block, D1757 tells us that verb unlock was unable to
find or infer a direct object and is prompting for one.
In this block, D1059 tells us that verb take requires that
direct objects not be scenery.
verbaction statements
verbaction statements show where
verb action hooks are called.
Action hooks are called during a verb's doTry and
doSuccess phases. They are specific to a given verb, and there
are any number of them, depending on the sentence structure of the input.
Authors can use them to inject custom code that overrides default
doTry / doSuccess behavior.
Expand for verbaction examples
This block shows where verb actions are called in response to the player examining the pitted cobblestone. An author can hook into any of the functions shown here to inject custom code. Where you see an item like HOOK pitted_cobblestone.tryExamine(), it is indicating that if there is a method by that name on that asset, it will be called here.
This block is very similar to the prior block, but see how the verb actions are called in response to the player opening the pitted cobblestone vs examining it. Though both apply to the cobblestone, the actions are specific to the verbs that called them.
The verb take calls another unique set of verb actions.
Authors can use these to hook into specific verb/noun interactions.
verbreaction statements
verbreaction statements show where
verb reactions are called.
Reaction hooks are at the end of a verb's doSuccess phase.
Multiple verbs may result in the same verb reactions, for example moving one
thing into another thing via put, take,
drop, throw, etc. Authors can use these to inject
custom code when one or more assets react in a certain way to a verb action.
Expand for verbreaction examples
This block shows where verb reactions are called in response to moving the
player from one room to another, which in this instance is a reaction to
the verb go. Where you see
HOOK, that's an instance of the parser checking the object of the input for a
method with this name. Where you see
↳ FOUND,
that's the parser finding a matching method on an object. Any of the
functions shown here can be used to run custom code.
This block shows where verb reactions are called in response to moving the
statuette from its original location into the player, which in this
instance is a reaction to the verb take. Any of the hooks
listed here can be used to inject custom code.
verbphase statements
verbphase statements show where
verb phase hooks are called,
including doBeforeTry, doAfterTry,
doBeforeSuccess and doAfterSuccess. These phases
wrap around the doTry and doSuccess phases that run
a verb's default logic. Authors can use verb phase hooks to inject custom code
that preempts or appends the default logic for specified assets.
Expand for verbphase examples
This block shows where verb phases are called when verb
open is applied to the pitted cobblestone. The functions that
are shown here don't exist until an author defines them, and are only
called if found. For example, placing code at
pitted_cobblestone.dov.open.doBeforeTry()
will let you preempt the verb's doTry() phase. Placing code
at
pitted_cobblestone.dov.open.doAfterSuccess()
will let you run additional logic after the end of the verb's
doSuccess phase.
This block shows where verb phases are called when verb
take is applied to the pitted cobblestone. In actions with a
direct object and an indirect object, both objects have unique verb
phases. This allows authors to attach custom code to any asset. For
example, placing code at
beaten_iron_key.dov.take.doBeforeTry()
is, in this context, equivalent to placing code at
pitted_cobblestone.iov.take.doBeforeTry(). Code placed at either location will let you preempt the verb's
doTry() phase specifically when a player attempts to remove
the key from the stone. This gives an author precise control over
interactions between assets.
Further reference
In addition to debugging to the display, there are also console logging options.
Verb hooks are a big subject that may be hard to get the hang of at first. To learn more, see these tutorials: