Posts Tagged ‘zifmia’

I’ve written several times about the development of a client-server Interactive Fiction platform. Parts of this system are called FyreVM, Zifmia, and other parts are just plain old web application development. FyreVM was created years ago and is a very stable implementation of the Glulx virtual machine. Zifmia is a state-machine wrapper that allows FyreVM games to run on a web server with all of the commands coming through AJAX calls and output returned as JSON. I wanted to provide a more detailed view of the new Textfyre system’s construction.

Technology
I spent a good portion of my spare time last summer working through the technical issues of a client-server implementation of FyreVM/Glulx. I’d had a very rough prototype, but last summer I sanded down the rough edges and came away with something solid. There were still major issues to resolve, including the design and persistence, but eventually I was able to send commands into the server-side engine and receive story data and display it on a web page. The next step was to turn it all into something “enterprise” ready. Something that initially could handle hundreds of users, but also be able to scale.

The first thing I worked on is making a reasonably clean “library” of JavaScript and jQuery code that was layered and maintainable. I then took all of that code and implemented an ASP.NET MVC 3 website. This allowed me to implement Clean URL’s, but also has a built-in capability for creating RESTful web services. It also allows me to continue using C#, since that’s how FyreVM and Zifmia were coded.

An additional benefit to using RESTful web services for all game play is that other types of clients can be developed later (iPad, Android, Windows 8 Metro).

Storage
One of the primary differences in this approach is that all of the game data is stored on the Textfyre servers. You might call it Cloud-IF since the player could conceivably play the same game from many computers and devices without any concern for saving, restoring, or managing files. The system stores the results of every turn and provides a user-interface that lets the player “jump” to any historical turn. The user interface even tracks branches, so the player can see where they jumped and where they changes paths.

This is done using Eloquera, an object-oriented database. It allows for very simple storage and retrieval of session data.

Design
Not to stress this too much, but designing a modern user interface for Interactive Fiction is very difficult. Juhana Leinonen set the standard with his Vorple demonstration a year ago at PAX East. Jon Ingold and his partner Joseph Humfrey are doing some amazing things at Inkle Studios (Note: Jon Ingold is the co-designer and writer of Textfyre’s The Shadow in the Cathedral). I’d like Textfyre’s offering to be capable of similar results.

Styling
With that in mind, I’ve left all of the styling capability of this system to external resources. I considered adding a bunch of CSS capability to an Inform 7 extension and asking the author to work under those constraints. After a few passes, this was simply tiresome and very much the wrong direction. I designed the IO of FyreVM to be design neutral for a reason. I believe firmly that content should not know about how it is formatted; outside of emphasizing text with boldface, italics, or similar in-line styles. Any placement or styling beyond that should be handled by the content type. Since FyreVM allows the author to channel output to different content types, this is easily handled in the “interpreter”. In this case, the browser is our interpreter. We simply take content types and associate them to browser placement and styling.

Templating
The next assumption I made was that whatever template I designed was only going to be the default or standard template. There are a set of guidelines for authors or anyone interest to develop their own template. It may be daunting for an author and certainly a non-programmer to develop a template using HTML5, but it’s certainly not impossible or even improbable. I think the results of Vorple and Inkle Studios is confirmation that the IF world has the talent.

The standard template is very similar to a standard desktop interpreter with a few changes. Images can be identified by the game by filename and embedded in-game play, a map can be identified, and a few other visual elements allow interaction with the game, including displaying the player’s current inventory.

It would not be difficult to modify the standard template to move things around. Swapping in a new CSS file could change the entire design, similar to the way CSS Zen Garden works.

Web Services
I mentioned that game play is implemented using RESTful web services. Each service is called with a Clean URL and returns JSON (JavaScript Object Notation). HEre is a list of all of the possible web service calls (all executed through HttpWebRequest, always from a jQuery command):
Register player – /Register/{username}/{password}/{nickName}/{emailAddress}
Player login – /Login/{username}/{password}
Is Authorized – /IsAuthorized/{authKey}
Validate Player – /ValidatePlayer/{validationId}
Session Start – /SessionStart/{authKey}/{gameKey}
Session Get – /SessionGet/{authKey}/{sessionKey}
Session History – /SessionHistory/{authKey}/{sessionKey}/{branchid}/{turn}
Session Command – /SessionCommand/{authKey}/{sessionKey}/{branchId}/{turn}/{command}
User Session List – /UserSessionList/{authKey}
List all installed games – /Games

Game Data
When the player enters a command, it’s sent to the Session Command web service. This service executes the command and gathers all of the data. This data has always been called “Channels”, but you could also call it labelling. When the author is emitting text in a game, there are different kinds of text. FyreVM automatically determines most of the types and labels them accordingly. So the room title and description get labelled “Main”. The room title also is labelled “Location”, the score is labelled “Score”, time “Time”, turn “Turn”, and so on. The list of standard labels includes:

Prompt This is the text that precedes the prompt. In a standard IF game, this has always been “>”, but in our system, it can be any normal text.
Main This is the main text of the game, which includes any ‘before’ text, the location title and description, any object lists, and ‘after’ text.
Time This is the time of day within the game. It’s not always implemented or used, so the standard template looks at the Settings text to see if it should be displayed or not.
Location This is the location name.
Chapter If a game implements chapter titles, this is that text.
Credits This is the list of credits for the game.
Hints This is the current list of hints for the game. This data has to coordinate with the browser properly, so modifications to the standard template are required.
Score This contains the current score, if one is offered. The Settings text will identify if a score is displayed or not.
Title This is the game title.
Prologue This is the text displayed in the ‘When play begins’ rule of the game.
Turn This is the current turn number.
Tips This is a tip for the player.
Version This is version of the game.
Verb This contains the verb in the last command.
Tutorial This contains tutorial text.
Maps This contains a map image filename or some other text to show a map to the user. The standard template uses images (that change throughout the game).
Dead This is the text emitted when the game has ended.
Settings This text contains information on whether other types of text should be displayed or not.

Authors can dynamically label alternative content, which can in turn be displayed in the browser based on author preferences.

All of this data is returned in JSON and looks like this (this is an excerpt from a running version of Cloak of Darkness):

"Channels": [
{"Name": "PLOG", "Content": "Hurrying through the rain-swept November night, you\u0027re glad to see the bright lights of the Opera House. It\u0027s surprising that there aren\u0027t more people about but, hey, what do you expect in a cheap demo game...?"},
{"Name": "CRED", "Content": "Cloak of Darkness by David Cornelson\nGame Engine (FyreVM) by Jesse McGrew\nZifmia by David Cornelson\nInform 7 Programming by Emily Short and Graham Nelson, with Channel IO updates by David Cornelson.\nSpecial thanks to Graham Nelson and Emily Short for all of their hard work on Inform 7."},
{ "Name": "SCOR", "Content": "0"},
{ "Name": "TUTR", "Content": "You might try going WEST from the Foyer of the Opera House"},
{ "Name": "TIME", "Content": "540"},
{ "Name": "LOCN", "Content": "Foyer of the Opera House"},
{ "Name": "PRPT", "Content": "What do you want to do next?"},
{ "Name": "MAPS", "Content": "cloakmap-dark.png"},
{ "Name": "MAIN", "Content": "You are standing in a spacious hall, splendidly decorated in red and gold, with glittering chandeliers overhead. The entrance from the street is to the north, and there are doorways south and west."},
{ "Name": "TURN", "Content": "1"},
{ "Name": "TITL", "Content": "Cloak of Darkness"}
]

There’s a framework in place to convert the JSON data into a known JavaScript class, so “PLOG” becomes game.Prologue and “LOCN” becomes game.Location. This can then be displayed by updating the web page through a jQuery command, like this:

$("#promptText").text(game.Prompt);
$("#locationTitle").text(game.Location);
$("#chapterTitle").text(game.Chapter);

Summary
The new Textfyre website is nearly completed and in coordination with several eReader publications, is due out soon. It’s taken a long time to work through all of the technical details, but I think the results will be very attractive to Interactive Fiction game players as well as authors, teachers, and educational content providers.

I know no one gets excited about vaporware, but the new Textfyre website will address some of the issues Jim talks about here.

Based on my work on Zifmia, which is a client-server engine based on FyreVM, which is a .NET implementation of the Glulx specification, I have been able to build a new Textfyre website. This new website is intended to be a portal for client-server Interactive Fiction games.

Here is the scenario I envision for the portal:

An author uploads a gblorb file that contains their game and images. In setting up their game, they select a template, which is used to display the game in any supported browser, including mobile and tablet browsers. The template is made up of JavaScript, HTML, and CSS. The author may offer their own template and a way to test templates locally will be enabled. The ability to use the portal in an IFRAME will also be available, allowing the author to show the game on their own website or blog. Facebook integration is an important part of the future of Textfyre’s strategy as well.

Games are played in a standard fashion, but mostly based on whatever template is devised. The template I’m working on is a hybrid of things we’ve seen over time and a slightly out of date version can be seen at http://beta.textfyre.com.

One of the major differences with the portal is that every turn of every game is saved on the Textfyre servers, in the cloud. If you play the game on any connected device, you will never lose your places. Save, Restore, and Undo become irrelevant. The user interface will have a mechanism to jump to any turn the user has played. If they type a new command at a previous turn, the history branches. These branches are displayed to the user and can be panned and zoomed and reviewed.

Obviously, this is a connected service. Future implementations may include client-side storage, but it’s not on the radar today.

I have Cloak of Darkness working as an example. I’m still (slowly) working on the standard template and Shadow will be implemented as a pay-to-play game when the site is released publicly. Secret Letter will follow and we’re working on getting Empath’s Gift completed, at which time it will also become a part of the portal.

I would love for an author to step up and offer to work with me on the standard template or a new template for their own game. If anyone is interested, let me know. This is mostly going to be undoing any Glk specific code in your game file and replacing it with FyreVM stuff and then working on the client-side code.

Overheard on ifMUD last week was an observation-only comment about Zifmia being vaporware. I was amused by the comment, since I have made great progress on the entire project in the last few months. I just haven’t been talking about it all that much. Since there has been no demonstration of Zifmia and no public discussion, the vaporware comment was accurate.

However, that is all about to change. I have a working system and although I’m slightly side-tracked with a potential investor meeting on the 16th, a beta of Zifmia is coming this month. The beta will be a replacement of the entire Textfyre.com website into a game portal for Interactive Fiction developed with Inform 7, FyreVM and Zifmia extensions, images, js, css, and html.

A version of Cloak of Darkness will be present in the beta along with a demo version of Shadow in the Cathedral. A full version of Shadow will be added when the payment system is ready. Other features will be added over time, including the ability to upload your own games and web provisioning. I intend the beta of the new Textfyre website to be an extended period of time, to let the kinks iron out.

One of the first tasks will be to adapt extensions for the “standard” Zifmia design, which will be very simple. You can see a functional sample of the latest standard design at http://textfyre.com/design/zifmia-design-2.html. The opening page is a templated “prologue” and following a press of any key, the main template is displayed. Currently there is a column of main text, some spot art, fly out text windows on the left and right, a command line text box, along with map and hint buttons.

Templates are based on straight HTML5/CSS3 using jQuery and various jQuery plugins. I’ve tested this design with IE9, FF 5, and Chrome. It does not work on mobile devices as I see that as a separate template entirely. I plan to investigate jQuery Mobile to help with that work.

I plan to move forward with this design and implement an Inform 7 extension to implement the various pieces. It shouldn’t be too hard to create simple Inform 7 markup that translates to html with known classes.

Feel free to test it out and leave comments.

 

On the way to PAX East I had intended on getting a new version of Zifmia ready to show at the Demo Fair. It was a lofty and unreasonable goal, given the changes I was making to the service. There were several issues, including adding the very complicated branching capabilities as well as refactoring large swaths of the code.

After PAX, I was continuing this work and getting frustrated with the mapping between the Zifmia object model and data storage. I was using SQL Server, which is fine for most things, but I just thought a simple object storage system would be more suitable, especially given the availability of using Linq, a Microsoft invention that allows native code queries on lists of objects.

A typical Linq query goes something like this…say I want to find a session.

ZifmiaSession session = (from ZifmiaSession s in db where s.Id = sessionId select s).FirstOrDefault<ZifmiaSession>();

I can do this if “db” is an object-oriented database or if I’ve implemented some mapping tool to allow for this type of query. With an object-oriented database that implements Linq, I can retrieve anything with one line of code. I can’t tell you how much easier this is to code, test, and deploy.

So I went looking for an oodb that met my requirements, mostly that it was free, had Linq capability, and performed well. I [played around with a few commercial products like DB4O, but eventually settled on Eloquera.

Eloquera has turned out to be an enormously helpful change in Zifmia’s inner workings. The code is much smaller, cleaner, and just as fast as SQL Server had been.

Over this past weekend I finished up the unit testing, got the original AJAX regression test working, and the code is in pretty good shape. I may still go through one more refactoring, but that will be later. The goal now is to implement user interfaces, clean up anything I missed, and get games out.

The code is currently checked into the FyreVM repository on SF.Net, but will move to its own Zifmia repository soon.

Web/Facebook, iPad, Android Tablet, and more UI’s are on the way along with games games games.

Me: So how does Zifmia work again? The user registers, logs in, fires up a game from a list of installed games?

Me: Yes. Internally, there is a register service method that returns a registration object, a login service method that returns credentials for further access to the service layer, a list games service method, and a session/start service method. The last one returns a session object that contains mostly everything a client needs to draw the user interface.

Me: The can enter a command to progress the game?

Me: Yes. This is the session/command service method that also returns a session object. Internally, after a started game and after every command, some other work is going on. This includes saving transcript text and history data.

Me. So then the user backtracks and wants to go in a different direction. Do they use save and restore to do this in a Zifmia client?

Me. No. Save and Restore are meaningless in Zifmia. The service keeps track of every turn, every command, and stores the game data for every turn. The user can go back to any point and the server will reproduce the results of that turn and simply resend the session data to the client. If the user wants to “branch” off into a new direction, they would be starting a new session, but the service keeps track of branching sessions.

Me. So a session is a branch or the whole tree?

Me. Um, Um,  $*$#()( segfault 940394 $(#)$(#)……

…..rebooting…..

Me. You okay?

Me. Affirmative, Dave. I read you.

Me. Good. What happened?

Me. Well you said “session is a branch or the whole tree” and I had been working on the assumption that it was a branch, but it’s really the whole tree.

Me. Then what’s a branch?

Me. I think you know what the problem is just as well as I do.

Me. I do, but you can explain it better.

Me. Okay here it goes. When a user start a game, the service creates a session. The session has a current branch number, which the user never sees. The session also has a current turn number, but we’re going to call that node. The service will track each turn as a node. A node is of a session and a branch. If the user backtracks and enters a new command at any node, the service checks to see if any other node matches that command (it would have to have the same parent or be the root branch). If there is an existing node, that node’s data is returned to the client. If not, a new node is created, with a new branch number, the command is executed, and the results are returned, as a node, to the client.

Me. “Node” is very mathy. Could you rename it?

Me. I’m sorry, Dave. I’m afraid I can’t do that.

Me. Okay.

Me. So I have a lot of work to do. I have to refactor several objects and create a few new ones, change the service layer, update the javascript client, and update the regression test.

Me. Sounds boring. You should get outside more.

Me. Dave, this conversation can serve no purpose anymore. Goodbye.

I’m still working on the web client for Zifmia and it’s going slow, mostly because I keep changing the AJAX interface to get everything so it’s compact and very simple. There’s a regression test working now at http://zifmia.textfyre.com/regressiontest.html. The tests include registering a user, logging in, listing games, starting a game session, sending a command to that session, getting a session, getting a previous turn in a session, and then listing all sessions for a logged-in user.

The clientside javascript is wrapped up in the following files:

http://zifmia.textfyre.com/scripts/strings.js – has an extension method on String that allows traditional formatting with arguments.
http://zifmia.textfyre.com/scripts/zifmia.js – the main AJAX calls to the Zifmia service
http://zifmia.textfyre.com/scripts/zifmia-controller-regression.js – the regression test implementation of the controller.
http://zifmia.textfyre.com/scripts/zifmia-controller.js – the sample imlpementation of the controller.
http://zifmia.textfyre.com/scripts/zifmia-htmlformatting.js – has an extension method for converting text to html, currently only looks a newlines and turns them into BR tags.

There’s a jquery-min.js file in there as well…I think I have 1.3, but should upgrade to 1.4.

* * * *

I took the plunge this past week and purchased an iPad 2 and a Mac-Mini. Paid extra for the iPad and got a deal on the mini, both off of craigslist, so it more or less evened out.

I installed xcode 4 and with a lot of help from the gang on ifMUD, started getting an iPad client for Zifmia going. I have a lot of hoops to jump through, not to mention learning Objective C, but it doesn’t seem that hard right now. Just different crazy syntax issues.

My idea for the iPad client is similar to the web client, but it won’t be called “Zifmia”, it will be the Textfyre app. I plan to make the client free, but zifmia will allow games to be installed as pay per use games. The nice thing is that this will allow games to be installed in Zifmia that require payment or be free. I haven not figured out how this will work and am aware of the more draconian principals around Apple’s pay for content model, but this seems like a reasonable direction.

Anyone that builds their own client is still free to do so. I may have to split the server into two installations, one for Zifmia and one for Textfyre, but for now I’ll leave it in a merged “beta” state.

As for the iPad client itself, I envision being able to type in commands as usual, but being able to swipe backwards for previous output (one turn per page), have expandable live mapping, note taking, comments at a given location for a given game-state (I’ll have to figure out how to manage this so we don’t show spoilers), common commands used by other users, and local play with a built-in FyreVM engine that resyncs to the server when it can.

I’m less interested in smartphones now. The tablet is the way to go and I’ll have to look at doing the same work on the Galaxy Tab or other Android tablets.

As I work through the minor technical issues of Zifmia, both client and server, some questions have arisen that seem important to how one might develop new games….specifically for the web world.

First of all, we intend to remove scrolling output from the web client paradigm and replace it with paging. Every time you interact with the game engine, we’re going to store the response. Within the UI, you will then be allowed to “page” backwards (and then forwards) through the entire history of your play. Unlike a scrolling UI, the UI stays the same, only the content changes. One of the interesting changes this has on your perception is that the most important aspect of the screen is the current setting (or location). Well, that was important in scrolling too, but my experience is that the setting change and non-change turn over turn is much more impactful. If you’re interacting in the same setting for a number of turns, the static UI feels much more that you have not moved than in a scrolling UI.

I’ve also been toying with the idea of polling for responses of non-movement and non-setting changing commands. So for every in-scope object, we’ll do an examine and search, store those responses in a data structure, then pass them to the client every turn. This means that the user can interact with all of the scenery without using a single turn. This adds to the perception in the static UI that the world is stable, grounded, and more realistic.

If we continue down this path, I envision having background art for each region in a game, further solidifying the realistic look and feel of the setting.

I’m sure there are more interesting observations coming as we experiement with Zifmia and client/server IF, but these are some of my initial thoughts.

Since getting the service layer running for Zifmia, I’m now focused on the client side look and feel and getting a first iteration completed by PAX for the IF Demo Fair. To that end, I’ve come up with a first draft of the wireframe layout.

As you can see, this is very different from previous Interactive Fiction UI designs. There are tabs on the right for different types of content. Popup menus that can auto-enter commands relative to a word in the text, a history of commands and recommended commands, a movement panel with all of the common directional verbs for auto-entering, a list of users (the lamp represents who is in charge of entering commands, everyone else is a watcher), an achievement panel, and a description panel (which will show the results of examine, search, and similar commands without using a turn – everything in-scope is known for every turn).

I’ve tried to keep the focus on words and reading as opposed to images, but this the first foray into developing a Zifmia web client and I wanted to try to stay somewhat generic. Future, game-specific user interfaces could have clickable maps, and other features. Eventually, Zifmia will allow a UI package to be uploaded that contains javascript, css, html, and images and tie the package to a game. Then when someone starts that game, the game UI package is used to display the game.

There is still one piece missing and I’m still pondering the implementation. The user can review previous turns. This data is stored on the server. So if the user has played 100 turns, how do we show this and how can we make it easy to select a previous turn or allow paging? This is a purely UI question. Technically, retrieving any turn is a simple AJAX call.

Since we’re using jQuery to design pages, we should be able to offer jQuery themes too.

I will also be adding oAuth to protect the service and offer pay games, web chat, and more.

I’m hoping to have the bulk of this design ready for PAX.

So I have a working version of Zifmia, a client/server implementation of FyreVM. Basically, this is FyreVM with a state management wrapper where state is stored on the server. The wrapper and engine are hosted in a web service. I started developing the client web behavior with very basic html controls and it’s now time to design and create something interesting.

I was wondering if anyone with mad jQuery/CSS/HTML skills might want to help out and that’s not even a request to actually write code. Even ideas on how to translate an IF game onto a web page would be great. For instance, I don’t plan to implement a running scrollable textbox with game transcript text. I want to develop a paging mechanism and use jQuery to make it fluid within the browser, so keystrokes will allow movement to previous turn output and returning to the latest “page”. I’d like to implement a CSS based compass rose that shows available visited exits and possible unvisited exits (I’ve recently implemented a new channel that reports, in XML, what the visted and unvisted exits are).

I’m not much of a designer and defintely not a jQuery/CSS developer. I also have many other tasks on my plate.

The result of any work is open source and will be documented and shared with the IF community.

So I had set aside a lot of IF work in the past month for work and health reasons. I found myself with a very bad case of whiplash after several wild rollercoaster rides at Six Flags which uncovered high blood pressure, which led to me to get a stress test, a physical, and to see a foot doctor. The neck pain and dizziness are gone, the new orthopedic shoe inserts are wonderful, and the blood work all came back normal. I feel better. Relieved.

I had left Zifmia in a nearly working state, outside of details like security and the client aspects. The server was very close to being completed. So I’ve spent the last three days working through the issues and it’s now running perfectly. Here’s what I did.

I’ve developed FyreVM in a new WCF web service. For newcomers, WCF is a framework from Microsoft that allows you to easily build web services. The service has a single interface, GetResponse:

    [ServiceContract(Name="ZifmiaService",Namespace="FyreVM")]
    public interface IZifmia
    {
        [OperationContract]
        [WebGet(ResponseFormat=WebMessageFormat.Json)]
        ZifmiaResponse GetResponse(ZifmiaCommand zCommand);
    }

The ZifmiaCommand is parameter class:

    [DataContract]
    public class ZifmiaCommand
    {
        [DataMember]
        public string SiteKey { get; set; }
        [DataMember]
        public string GameKey { get; set; }
        [DataMember]
        public string UserKey { get; set; }
        [DataMember]
        public string Command { get; set; }
    }

The main parts we’re interested in today are GameKey, UserKey, and Command. The GameKey is a reference to a server-side game file. The UserKey is a user’s identity. The Command is whatever the user has typed into the game window.

WCF has a built in test client that helps us test:

In the first frame, we’ve opened up our test client. We click on the GetResponse interface, which displays our available zCommand interface. Then we add in our start up arguments and invoke. You can see the results in the third image. Each channel has a value or is blank. Then we add a command and invoke a second time. This shows the channels again with different data. In the final image there is a couple of files that represent the state of the game. The main file is the save data and the numbered XML files are the channel data saved for each turn. We can re-use this data to display previous turns in the browser (or any application that consumes the Zifmia service).

It all works and is very fast.

Next up, the client with fancy jQuery controls to display our channel data.