CodingMonk

Subtext & JavaScript

Jim Fisher — Mon, 18 Aug 2008 04:52:34 GMT

It's been a few months, but I've finally gotten around to finishing an article promised months ago about configuring Subtext 1.9.5b to support images when blogging from Word 2007. As chance would have it, this comes just a week after Subtext 2.0 is released.

Additionally, I've updated and posted a document written a few years ago but never released offering ways to organize your JavaScript library. This article comes along side a new zone to this site: JavaScript.

Tips for Building a JavaScript Library

Jim Fisher — Mon, 18 Aug 2008 03:19:40 GMT

You're an experienced developer. You learned a long time ago how to make your code generic and factor it for optimum reusability, neatly organizing it into tight, independent packages. Need a multithreaded web scrapper? You have a C# assembly that does that, thank you. Logging to the event viewer from T-SQL? No problem, there's that script you developed a few years ago. Want transformed text embedded in a graphic? Got it covered. The toolkit you've built over the years equips you to easily handle almost any task.

Almost.

Well… There is that bit of untidiness with your JavaScript. But everyone has that, right? I mean, with the hundreds of snippets smattered across the internet how could anyone keep those straight? Sure, you've made the obligatory attempt. You put the most often used routines into a single common include file. But the file grows with almost every new project, and each project leveraging this file uses only a fraction of its contents. The practice of monolithic includes is… unsatisfying.

Fear not. There is a better way.

About this Article

This article describes some of the impediments that make fashioning and maintaining a library in JavaScript troublesome and discusses some techniques for surmounting these obstacles. These techniques have been adopted by CodingMonk and are manifest as the JACL (JavaScript Application Code Library) framework. As such, most of the examples are given in that context, yet the techniques described here lend themselves equally well to a personal implementation.

The code depicted here has been tested under both the Firefox and Internet Explorer browsers, including Microsoft's implementation of HTAs (HTML applications). I suspect that these techniques could also be ported to additional browsers (e.g. Opera, Safari) with minimal effort.

Before going further, I'd like to make it clear that my way is not the only way. There are a number of gifted JavaScript developers around the world and I expect there exist several additional techniques not covered here. Please keep in mind that what works well for me may not fit well in the preferences of another developer.

What Makes a Code Library?

A fundamental preconception that people have when they hear the word "library" is that it is a collection of smaller parts. Although I can lump all of my scripts into a single reusable file and call it "Jim's library", that doesn't really hold true to the spirit of the word. Likewise, just as we wouldn't checkout every book from the shelves of a real library when researching English history, we shouldn't have to download the complete code when we're only using one or two of its features.

So, our library should be organized into functional modules from which we can pick and choose what we need.

This deceptively simple diktat is absent from the majority of JavaScript "libraries" available on the internet. Why? Because modules inject unexpected complexity into a library, especially highly functional ones leveraging other modules as dependencies. We'll identify some for these complexities and address them now. When we're finished, we'll have a basis upon which to build a working, expandable framework for our JavaScript library.

Modules Including Modules

As a code library matures, it's almost a given that one module will eventually need to include another. In JACL, for example, the Log module is automatically included by the Core module, so logging functionality is always available. Another example: each of JACL's self-updating controls leverages an AJAX implementation housed in the ServerRequest module.

So how do we include a JavaScript file from within another JavaScript file? Obviously the most common way to include JavaScript from HTML is with the script tag:

So from within a JavaScript file, one possibility is to leverage document.write() to inject customized script tags whenever a library module needs to meet a dependency. A la:

document.write( "<script src='http://www.codingmonk.com/jacl/jacl.js'> </script>");

One complication associated with dynamic inclusion of JavaScript: it is not immediately obvious when the included file has successfully loaded. Despite their similarities, it's easy to forget that the above two lines are not exactly equivalent. To be precise:

The first, declared within the HTML document, includes the JavaScript file while the page is first loading, but before scripts are run.
The second, processed after the page has finished loading and declared scripts are running, identifies subsequent scripts that the browser should load when it gets the opportunity.

So as rule: JavaScript included from JavaScript is not immediately available, but JavaScript included from a tag in the unmodified HTML document is.

To demonstrate, we can do this:

<html>

jacl.appMain = function(){alert("Something wicked this way comes...");};

</script>

</html>

But we can't we do this:

<html>

document.write( "<script src='http://www.codingmonk.com/jacl/jacl.js'></script>");

jacl.appMain = function(){alert("Something wicked generates an error...");};

</script>

</html>

Because the second example produces an error message in the spirit of "jacl is undefined".

A more sophisticated alternative is to leverage the browser DOM, like so:

<html>

var o=document.createElement("script");

o.src="http://www.codingmonk.com/jacl/jacl.js";

o.onreadystatechange = function(){

if(this.readyState == "loaded"){

jacl.appMain = function(){alert("Something wicked this way comes...");};

}

};

document.body.appendChild(o);

</script>

</html>

Use of the DOM to dynamically load JavaScript provides a solution to our problem in the form of the onreadystatechange event. This event fires only when the script has loaded completely, at which point we can reference functions and objects provided by the included file with impunity.

Initial Module Inclusion

Despite the DOM example in the last section, the practice of including JavaScript from JavaScript gains us nothing when used where traditional HTML script tags are possible. If used appropriately, it enables us to manage our library entries and their dependencies intelligently, but it is still necessary to include the first module by hand.

This brings us full-circle to the first code snippet listed in this article:

As it turns out, there is considerable usefulness in including an initial module as we would include a traditional script file. It provides for us select core routines without having to wait for a load event, including implementation of principals discussed above which load modules programmatically. Additionally, it gives us a place to perform library initialization. This can include, among other things, an application-defined entry point where we can be certain all library modules are loaded and ready.

To demonstrate, below is a working example of an HTML page leveraging JACL's Plot module to draw a sine wave. For those that are curious, it can cut-and-pasted into an html file and viewed it in any browser.

<html>

<body>

jacl.use("jaclPlot");

jacl.appMain=function(){

jacl.plot.setOrigin(50,100);

jacl.log.info('Graphing sine wave...');

for(var t=0;t< 300;t++)

jacl.plot.point(t,Math.sin(t/30)*30);

};

</script>

</body>

</html>

Notice that our initial inclusion of the now familiar JACL Core module is done explicitly as an HTML tag. This ensures that the library's objects (in this case the jacl object) are present, as are library defined code. In the JACL framework, this includes the use method, which is simply a refined implementation of the DOM principals discussed in the previous section, and the appMain method which is similar in principal to the onreadystatechange event but fires only once when all modules have finally been loaded.

Avoiding Multiple Inclusions

Another complexity inherent in the practice of modules-including-modules occurs when two modules share the same dependency. If not handled, the same module can be included twice. The worst case scenario results in self-referencing recursion and a page that never finishes loading.

The simplest solution is to set a flag when a module is included for the first time, doing nothing on subsequent inclusions. By leveraging our object hierarchy, this is almost laughably easy as the individual objects created by a module act as flags simply by virtue of their existence:

if(jacl.plot==null) { //already created?

jacl.plot=new jacl_plot(); //no? then let's create an instance

// implementation goes here

}

The only drawback to this is that, while easy, the approach must be enforced across all library modules. A better alternative, one that can be implemented in the library object itself is to track which modules have been already been requested and don't add them via the DOM more than once.

Establishing a Library's Location

Astute observers will notice one important nuance in the sine wave example:

jacl.use("jaclPlot");

The use method does not require a fully qualified file path. At first glance this seems a trivial feature. After all, if we need to specify the URL when we include one module, it is only a small inconvenience to provide the URL with subsequent inclusions. The real problem arises, again, when modules include other modules. In the example where we included modules with the DOM, the path was hard-coded, as in:

o.src="http://www.codingmonk.com/jacl/jaclPlot.js";

This isn't going to do us any good if we try to access our library locally, or if we move it to a different domain. What we need is for the module to determine the library's location relative to the client. As it turns out, this isn't too difficult. Since we're including an initial core module with a fully qualified filename all we have to do search the document's script objects and parse the path from the correct one:

var path="";

for(t=0;t<document.scripts.length;t++){

var val=document.scripts[t].outerHTML.toLowerCase();

if(val.indexOf("jacl.js")==-1) continue;

var s=val.indexOf("src=\"");

if(s!=-1){

s+=5;

path=val.substring(s,val.indexOf("jacl",s));

break;

}

So the use method knows to expand:

jaclplot

into

http://www.codingmonk.com/jacl/jaclplot.js

by using the resulting path variable. Of course, storing the path as a global variable clutters the namespace. This is just one of several advantages of leveraging an object hierarchy for our JavaScript library…

Organizing a Hierarchy

The best, most useful of libraries can suffer and die because it is not kept organized. As libraries grow, they become more difficult to keep arranged. No matter how many modules your library is broken down into, if the net result is just a chaotic bundle of routines, then the library hasn't helped as much as it could.

Namespace hierarchies help us to stay organized. More than just factoring code into modules, this technique structures our code in precise and predictable ways. Notice from our examples how every use of the JACL library stems either directly or indirectly from the global jacl object. JACL's implementation of the previous path-finding example populates a member variable rather than a global one:

jacl.path

By doing this, we need not worry ourselves with the possibility of naming collisions, where another module or otherwise appropriated script defines a variable named "path" too.

Continuing the review of the fully working sine-wave example given previously, notice that JACL's logging module adds an object which encapsulates various pieces of logging functionality:

jacl.log.trivial("Here is a message");

Other JACL modules go to greater lengths to categorize their code:

jacl.input.textbox.applyEditMask(tbInput, "###-##-####");

How diverse you choose to make your hierarchy is, of course, a personal preference.

Review a real implementation

As was pointed out numerous times, the techniques proposed in this article are more than theoretical. For a complete working example, one moderately more fleshed out, I highly recommend taking a look at the most recent implementation of Coding Monk's JACL framework:

www.codingmonk.com/jacl/downloads/jacl.zip

Happy coding!

Configuring Subtext for Blogging with Word 2007

Jim Fisher — Mon, 18 Aug 2008 03:02:12 GMT

As part of my political agenda, in a recent post I walked through the steps of configuring Word 2007's blogging features to work with Subtext. At the end of that article, I promised to review the code changes required to make Subtext accept pictures from Word 2007. The fix I detail here consists of relatively minor code changes, limited to two c# files in the Subtext.Framework project:

MetaWeblog.cs
MetaWeblogAPI.cs

If you regularly compile the Subtext source code, you'll find making these changes a snap. If not, you might find it easier to skip the rest of this article, navigate to your site's bin directory, rename the Subtext.Framework.dll file and drop this one in its place.

Before moving forward, I should note that the changes described are against the Subtext 1.9.5b code base and future versions of the code base probably have this incompatibility addressed, so a bit of advice: make sure which version of Subtext you are using before you begin digging into the internals.

MetaWeblogAPI.cs

If you crack open the MetaWeblogAPI.cs file (under Subtext.Framework.XmlRpc) and search for the newMediaObject method, you'll find the following under the IMetaWeblog interface:

[XmlRpcMethod("metaWeblog.newMediaObject",
Description = "Uploads an image, movie, song, or other media "
+ "using the metaWeblog API. Returns the metaObject struct.")]

mediaObjectInfo newMediaObject(object blogid, string username,
string password, mediaObject mediaobject);

Note the blogid parameter is of type object, unlike every other method in the interface, which all support blogid parameters of type string. The easiest fix in this module is to change the change the parameter type to string, and I suspect that this alone might solve the issue, but a more thorough approach, one that leaves compatibility for other applications that may actually use the object-based blogid, is to add a more specific declaration or two. I chose this path of overkill, rather than that of minimalism by adding support for both string and int types; while not strictly necessary, it was quite easy to do. The full definition of the newMediaObject declaration appears below, with the additions surrounded with a dotted border:

[XmlRpcMethod("metaWeblog.newMediaObject",
Description = "Uploads an image, movie, song, or other media "
+ "using the metaWeblog API. Returns the metaObject struct.")]
mediaObjectInfo newMediaObject(string blogid, string username,
string password, mediaObject mediaobject);

[XmlRpcMethod("metaWeblog.newMediaObject",
Description = "Uploads an image, movie, song, or other media "
+ "using the metaWeblog API. Returns the metaObject struct.")]
mediaObjectInfo newMediaObject(int blogid, string username,
string password, mediaObject mediaobject);

[XmlRpcMethod("metaWeblog.newMediaObject",
Description = "Uploads an image, movie, song, or other media "
+ "using the metaWeblog API. Returns the metaObject struct.")]
mediaObjectInfo newMediaObject(object blogid, string username,
string password, mediaObject mediaobject);

These are, of course, only slight variations on the original declaration.

MetaWeblog.cs

Having declared the additional forms of newMediaObject that Subtext will support, we are half way complete. The final changes that are to be made are contained in the MetaWeblog class. Search for the implementation of newMediaObject and you'll find the original signature:

public mediaObjectInfo newMediaObject(object blogid, string username,
string password, mediaObject mediaobject)

Note the blogid parameter with the type object. I found it best to not change the existing code. Instead, we need only to implement the two additions defined for the interface supporting the two alternate parameter types. Implementing pass-through methods for this is the least painful of approaches:

public mediaObjectInfo newMediaObject(int blogid,
    string username, string password,
    mediaObject mediaobject)
{
    return newMediaObject(blogid.ToString(), username,
        password, mediaobject);
}
public mediaObjectInfo newMediaObject(string blogid,
    string username, string password,
    mediaObject mediaobject)
{
    return newMediaObject((object)blogid, username,
        password, mediaobject);
}

And that's pretty much it for changes to Subtext. After we compile this and deploy the resulting modified Subtext.Framework assembly, Subtext should support images from Word 2007.

As Part of My Nonsense…

Jim Fisher — Sun, 17 Aug 2008 16:33:28 GMT

If you've been reading my blog for long, you may have noticed a common trend across some of my larger pieces: a bit of text expressing background to the article and indicating that it is part of a larger, personal effort:

"As part of my political agenda…"
"As part of my endeavors toward evangelizing the free world…"
"As part of my plan to stick it to the man…"

It doesn't take much review to realize that these are nonsensical statements, not to be taken literally, which serve as a form of unapparent signature when my articles are viewed individually, but which clearly mark my work when viewed as a whole.

Configuring Word 2007 for Blogging to Subtext

Jim Fisher — Thu, 15 May 2008 06:32:03 GMT

As part of my need to clearly express myself, I've been writing and posting articles on various sites for some time and, for me at least, the process has always been a painful one. For years I'd write the articles in Word, paste the completed document into Visual Studio, clean up the resulting HTML and formatting by switching back and forth between the source and the display panels, and finally upload the completed HTML to my site's database. Not exactly a roadblock, but this was certainly a speed bump in the creative process.

Beginning with Word 2007, Microsoft introduced a feature that removes the middle man and significantly streamlines the process of publishing articles online: Word now talks directly to blogging systems, including Subtext (the blogging framework upon which this site is based)!

I'm not the first to post on Word's new blogging features. In fact, I'm a bit late to the game; however, much of the research I turned up on Word 2007's blogging functionality didn't actually apply to what I was trying to do and a few sites alluded to steps that needed to be taken but didn't provide much in the way of details. So this post documents my own personal experiences on configuring Word to work with Subtext. On the whole, I thought it was relatively easy and I find blogging with Word 2007 a positive change, the advantages of which outweigh the drawbacks. Your mileage may vary.

Basic Word Configuration

Configuring Word2007 for blogging with Subtext is a snap and if you've never done it before, you'll get prompted to configure just by opening a new, blank blog entry. That is:

click your friendly office button:
select New
double click the New blog post option:

At this point, Word detects that you have no blogging accounts setup and prompts you to create a new one. Word comes preconfigured with a slew of blog providers, but at the time of this writing, Subtext is not one of them. That's okay though; as I said before, configuring Word is really easy. So from the Blog dropdown, just choose "other" and click the Next button:

Beyond the username password (which you presumably know if you actually blog to your site), there are only two settings to configure:

The API dropdown - For Subtext, this should always be set to MetaWebLog.
The Blog Post URL textbox – This is a bit less obvious, but it is the full URL of your Subtext site plus:
/services/metablogapi.aspx
That is, if your Subtext installation rests at www.mblog.com, then your Blog Post URL would be:
http://www.mblog.com/services/metablogapi.aspx
Those running short on faith (I'll pray for you, my brothers) might try to locate this file in their site's directory structure, just for reassurance that they have the URL correct. This will likely convince them that they managed to get their installation of Subtext fouled up when they find that this file does not actually exist. Don't be bothered by this. Subtext leverages a form of URL rewriting to make this address work; so enter this magic URL along with your username and password, secure in the knowledge that Word will immediately award you with a success or an error message as soon as you press the OK button.

Special Notes on Picture Options

To configure pictures, press the "Picture Options" button to pull up yet another dialog:

The default selection "My blog provider" is the correct setting for SubText, and for Subtext, this dialog need only be closed (press "OK"). Having made no changes, you might think that you can skip this step entirely, but my experience in this suggests that this open-and-close step is required and that support for pictures do not work unless this is done.

At this point I should mention that, as of the 1.9.5 release, SubText and Word 2007 do not exchange images. That is, pictures embedded in your post in Word, will not appear in your post when it's been published. This can be made to happen, and it's quite easy, really. I'll cover this in my next post.

Done Enough

Jim Fisher — Sun, 11 May 2008 03:46:41 GMT

It's been roughly two months since I tossed it all away and started over, but I think the site is close enough to actually begin using now. My last post listed six items I arbitrarily mandated as the criteria by with the site's skinning could be judged was "done":

Add support for post series
Implement syndication links
Update comment system
Polish up the UI (buttons)
Add a Subtext category
Incorporate traditional blog controls (like a tag clouds and archive listing)

Well, the first five are complete. "Done enough," I say.

So you might think the traditional blog controls would be the easiest to cross off my list, and you might be right. I'll definitely get around to it, but at the moment these seem less important to me. After all, there need to be blog postings before these controls become useful.

In addition to the five above, I also added a few additional features which did not exist before:

A layout button to expand and collapse the width of the site
A Preview button to preview what comments will look like once posted
A modification to the Subtext code base to allow Word 2007 to post images (I use Word as my blogging tool)

This last item, blogging to Subtext with Word 2007, will be the subject matter of my first post, by the way.

Stay tuned.

Advanced NPC Creation, Part 3: NPC Actions

Jim Fisher — Mon, 02 Jul 2001 05:00:00 GMT

Verb subroutines do it all. They enforce gravity; they differentiate between light and darkness; they decide where a character can travel. These little routines implement the laws of physics in our game world and govern what can and cannot be done. Yet for some reason, historically they only affect the player character. The game world laws that restrict the player do not bind NPCs. The following code exemplifies:

object room "room"

has light

with description "This is an empty room."

;

object->"guard" has animate

with name 'guard'

, orders [;

take: move noun to self;

print_ret (The)self," takes ",(the)noun,".";

]

;

object->"table" has static supporter with name 'table';

object->->"apple" has edible with name 'apple';

The guard has now been coded to respond to the "take" order and does so too well. In the above example, he will successfully "take" pretty much anything in scope, even things that he should not be able to:

room

This is an empty room.

You can see a guard and a table here.

>take table

That's fixed in place.

>guard, take table

The guard takes the table.

>guard, take self

The guard takes yourself.

It is now pitch dark in here!

Obviously this sort of "empowered taking" holds a very narrow slice of the "desired NPC abilities" pie. By convention, the filtering of what an NPC cannot do is also coded in the appropriate routine:

, orders [; !... replace the guard's previous orders routine

take:

if(noun hasnt static && noun~=player){

move noun to self;

print_ret (The)self," takes ",(the)noun,".";

}

print_ret (The)self," cannot take that.";

]

For the majority of Inform works, that's the way NPC action is accomplished. Piles and piles of example source code and sample NPCs follow this convention of manipulating the game world directly. There are some drawbacks to this, however:

This technique is repetitious. Putting the same rules in the NPC's reaction routines duplicates code that exists in the library's verb routines.
This technique can be overly complex. The library considers numerous variables in its efforts to implement the game world. It is very easy to overlook details when writing this sort of code. For instance, in the above example, the guard cannot pickup the player or objects with the "static" attribute, but there is nothing stopping him from taking either "untouchable" objects, or other animate objects. For instance, the guard could take a key contained inside of a locked, glass box (transparent) without breaking the glass. He could also take another NPC behind a locked, cell door. To imitate the library, we would have to code for these circumstances as well.
New verbs, such as "cast spell" or "mount horse" are unavailable to the NPC without additional coding too.
This technique does not respect an object's "before" routines, which may interrupt an action.
By its very nature, this technique limits NPC design, since everything that an NPC can do must be coded for explicitly.

Fear not, for there is another, more powerful way...

Redirecting to Verb Routines

A more intuitive solution is to leverage the verb routines themselves. Successful implementation of this method addresses all of the above drawbacks and actually makes the code more readable. At first glance, it seems a deceptively simple means of implementing NPC actions. Many new developers have posted questions to the RAIF newsgroup asking what was wrong with their code and why redirecting actions doesn't seem to work. The following is an example or redirecting an ordered action using the library's "action and return" operator (<<...>>):

object->"guard" has animate

with name 'guard'

, orders [; take: <<take noun>>;]

;

In the initial test of this example, everything appears to work fine:

room

This is an empty room.

You can see a guard and a table (on which is an apple) here.

>guard, get apple

Taken.

It is not until you look with a little more scrutiny that the flaw in this approach appears:

You are carrying:

an apple

The library's verb routines presume that the player carries out all actions. The player is therefore the one that actually picked up the apple. This is unfortunate, but not insurmountable.

Actor, Good; Player, Bad

The standard library is glorious. It is, perhaps, the most useful collection of IF routines ever created. To look upon the Library's code is to be humbled.

Now then, having appropriately praised the library, we can now proceed with a slightly more critical discussion of it. In particular, if there is one area where I feel the library should have been written differently, it is library verbs and messages. Specifically, these two aspects of the library rely upon the "player" variable, rather than the "actor" variable. See how forcing the player variable to momentarily equal the actor variable almost fixes the above behavior:

, orders [save retval; ! ... replace the guard's previous orders routine

save=player;

player=actor;

<take noun>;

player=save;

return retval;

]

>guard, get apple

Taken.

You are carrying nothing.

Of course this is simply a patch, and it prevents us from completing our implementation of NPC actions, as we'll see below. A legitimate solution would replace the library's verb and verb-helper routines with slightly modified versions that check the actor variable rather than the player variable. We can do this pretty easily to the "take" and "eat" verbs by cutting-and-pasting the appropriate routines from verblibm.h and then running a search-and-replace against them to change references to "player" into references to "actor":

!only slightly changed from the standard library

[ TakeSub;

if (onotheld_mode==0 || noun notin actor)

if (AttemptToTakeObject(noun)) rtrue;

if (AfterRoutines()==1) rtrue;

notheld_mode=onotheld_mode;

if (notheld_mode==1 || keep_silent==1) rtrue;

L__M(##Take,1);

];

[ EatSub;

if (ObjectIsUntouchable(noun)) return;

if (noun hasnt edible) return L__M(##Eat,1,noun);

if (noun has worn){

L__M(##Drop,3,noun);

<Disrobe noun>;

if (noun has worn && noun in actor) rtrue;

}

remove noun;

if (AfterRoutines()==1) rtrue;

if (keep_silent==1) rtrue;

L__M(##Eat,2,noun);

];

[ AttemptToTakeObject item ancestor after_recipient i j k;

...also needs to be updated since it is called from TakeSub

];

[ ObjectIsUntouchable item flag1 flag2 ancestor i;

...also needs to be updated since it is called from EatSub

];

As shown above, both TakeSub and EatSub call additional routines that also need to be updated in the same fashion. These are AttemptToTakeObject and ObjectIsUntouchable. We won't reprint the modified versions of these two routines since they are long and the changes are minute, but the point should be made that a simple search-and-replace fixes these as well.

Adding the four modified routines to your source code and putting the appropriate replace directives at the top makes the take and eat verbs available to the NPC without having to change the value of the player variable.

replace TakeSub;

replace EatSub;

replace AttemptToTakeObject;

replace ObjectIsUntouchable;

Also, ObjectIsUntouchable is called by numerous other verbs, and TakeSub is called by derivatives verbs. By replacing these four routines, we have also automatically made available to NPCs, all of the following routines and thus their corresponding verb forms:

TakeSub
EatSub
PullSub
PushSub
TurnSub
LockSub
UnlockSub
SqueezeSub
SwitchOnSub
SwitchOffSub
EmptySub
RemoveSub
DisrobeSub
WakeOtherSub

Since so many verbs are available to the NPC we will now drop the use of the library's "action" operators (<...> and <<...>>) in favor of the library's more generic routine, ActionPrimitive. This allows us to forego addressing the implied switch(action) statement that exists in all "reaction" routines (such as orders, life, before, etc...) and redirect all orders to the appropriate verbs with a single line of code:

, orders [; return ActionPrimitive();] ! replace the guard's previous orders routine

As we now have the ability to have the guard act for us, we can proceed with ordering him about and testing the affect of using "actor" instead of "player" in verb routines. Notice how drop, which has not yet been updated, does not function correctly:

>guard, get apple

Taken.

>guard, drop apple

You haven't got that.

>guard, eat apple

You eat the apple. Not bad.

What's with "YOU eat the apple?" It's understandable that the guard could not drop the apple since DropSub has not been updated, but why didn't the guard eat the apple?

Morphing Library Messages

Actually, the guard did eat the apple, but the default library message for the verb "eat" was written expecting the PC to be the only character eating. It, and many more library messages, will need to be changed to accommodate this whole new world of NPC actions. Usually, the recommend way of overloading a library message is to declare a LibraryMessages object between "Parser.h" and "Verblib.h" and implement it in the before routine. The following replacement for the "eat" message demonstrates this approach:

object LibraryMessages

with before[;

Eat:

if(lm_n==2){

if(actor==player) print "You eat ";

else print (The)actor," eats ";

print (the) noun, ".";

if(actor==player) print" Not bad.";

return;

}

];

Notice that the message now changes form depending on who is performing the action:

>guard, take apple then eat it

Taken.

The guard eats the apple.

or,

>take the apple then eat it

Taken.

You eat the apple. Not bad.

The number of library messages that need to be changed in order to implement NPC actions is somewhat excessive. Because of this, duplicating the language definition file (English.h) and making modifications there (specifying the modified file on the Inform command line or in the ICL file) may be a preferable method to instantiating a LibraryMessages object.

Initiating NPC Actions

For the examples given above, we have been calling ActionPrimitive() from within the NPC's orders routine. This has been convenient because all of the necessary library variables have already been set up for us. When the player is not issuing orders at run-time, however, we need to set these values ourselves. Additionally, there are another couple of complications that we must address:

1) The ActionPrimitive() routine does not honor the "before" property routines like "action notation" does (<<action>>); In order to achieve this we must make the call ourselves.

2) Floating objects may not be in scope for the actor.

These issues can be addressed in a common routine, which seems to be most at home as part of an NPC base class:

class NPC

with DoVerb[act n s svAL svActr svActn svN svS svInp1 svInp2 retval;

svAL=actors_location;

svActr=actor;

svActn=action;

svN=noun;

svS=second;

svInp1 = inp1;

svInp2 = inp2;

actors_location=parent(self);

actor=self;

action=act;

noun=n;

second=s;

inp1 = noun;

inp2 = second;

MoveFloatingObjects();

retval=BeforeRoutines();

if(retval==false) retval=ActionPrimitive();

actors_location=svAL;

actor=svActr;

action=svActn;

noun=svN;

second=svS;

inp1 = svInp1;

inp2 = svInp2;

MoveFloatingObjects();

return retval;

];

Additionally, BeforeRoutines() and AfterRoutines(), and MoveFloatingObjects() should all be modified in the same fashion as was discussed above. One exception to this "player equals actor" rule is in the call to the player's ORDERS property in the BeforeRoutines() method. This section of code should only be run if the player and actor are the same, otherwise an endless recursion results the will blow the interpreter's stack. A slightly modified BeforeRoutine() which addresses this follows:

[BeforeRoutines;

if(GamePreRoutine()~=0) rtrue;

if(actor==player && RunRoutines(player,orders)~=0) rtrue;

if(location~=0 && RunRoutines(parent(actor),before)~=0)

rtrue;

scope_reason=REACT_BEFORE_REASON; parser_one=0;

SearchScope(ScopeCeiling(actor),actor,0);

scope_reason=PARSING_REASON;

if(parser_one~=0) rtrue;

if(inp1>1 && RunRoutines(inp1,before)~=0) rtrue;

rfalse;

];

Assuming our NPC is derived from the NPC class, this addition will allow us to direct NPC actions from any section of code (like a controlling daemon):

guard.DoVerb(##PutOn, apple, table); ! equates to "guard, put apple on table"

A Peek Inside Pandora's Box

Perhaps the reason this technique is not often seen is the number of convoluted changes that need to be made in order to implement it. At times, implementation of this technique can seem horribly daunting.

The examples given above are far from complete. In addition to the excessive number of messages that must be modified, a quick scan through the verblibm.h file uncovers the following verb routines that need to be updated (only two of these were done in the above examples):

InvSub
TakeSub
DropSub
PutOnSub
InsertSub
TransferSub
GiveSub
ShowSub
EnterSub
GetOffSub
ExitSub
GoSub
LookSub
ExamineSub
LookUnderSub
ExitSub
TouchSub
WaveSub
PushSub
KissSub
ThrowAtSub
TellSub
AskSub
OpenSub
WearSub
EatSub

There are also several additional routines what are called by these verb subs that also need to be updated. Further, in many of these routines, there are references to the library variables "location" and "real_location." These need to be changed to the library variable "actors_location."

Obviously a complete implementation of this technique requires major modifications to the library, but once done allows for greater flexibility with simplified, yet more powerful, coding capabilities. Additionally, since the "actor" variable and the "player" variable are normally the same, these changes are transparent. That is, the new behavior only occurs when the new functionality is used and does not affect existing code. Without calling NPC actions, games run as they always have.

A Note on Code

The examples above were given to demonstrate this technique, but they do not necessarily represent the best way to implement it. The definition of what is "best" is left up to the reader. As a suggestion, however, rewriting messages to change form can be a convoluted and monotonous task. The print rules discussed in §1 of this article series "Pronouns on Steroids" are particularly useful.

As a final point, it should be noted that a complete implementation of the techniques discussed in this article can be found at the ORLibrary in the entries ORNPCVerb.h, OREnglish.h, and ORNPC_doverb.h.

Special thanks go out to Stephen Robert Norris, whose input and bug fixing in the ORLibrary necessarily impacted this article.