vorple.js

Is vorple.js available in a non-minimal version? I’m having a stab at learning more Javascript, and I’d very much like to see what’s going on in this code … but of course, vorple.min.js is unreadable.

Thankin’ in advance!

The up-to-date code is over at Github (vorple-if.com/vorple/doc/API/files.html).

Thanks. That’s extremely helpful!

Or at least, it would be if I understood Javascript better. I have a dim, hazy idea what’s going on here and there in the code, but there are plenty of details that elude me, and the big picture is murky indeed.

I know more about Javascript than I did last week; bought a book, been doing little experiments. I can see how to use an object as a namespace, for example, and why you would want to. I understand HTML and CSS, and what I don’t know I can look up. But I’m a long, long way from mastering Javascript. And that raises the inevitable question:

What’s a good way to learn it?

I’ve glanced at a couple of online courses, and what I’ve seen so far seems too basic to do me much good. I already know what an array is; I know what a for loop is; I know what the dot operator does, and how a function is structured. I don’t need to pay someone $300 to go over that stuff. I also spotted what might be a more advanced (and more expensive) online course, but it appears to be oriented largely toward eCommerce. As in, here’s how you validate a form. That’s not something I care about at the moment.

There are plenty of free tutorials online, but they seem mostly to give you little bite-sized tidbits of information. There’s no big picture, and the mental labor required to assemble bite-sized chunks into any sort of coherent overview – well, I’ll do it if I have to, but I’m hoping there’s a better way.

I bought “Javascript: The Definitive Guide,” and it’s really good, but it’s totally a reference work, not a tutorial. There’s very little in its pages in the way of concrete hands-on examples.

My local community college is useless. Two courses in the catalog on Web development – one far too basic, the other oriented toward eCommerce (and probably too basic).

What I want, ultimately, is to be able to look at something like undum.js or vorple.button.js and understand it, so that I could, like, customize it if I need to. Somehow I’m not sure there are any college courses in that. I’m sure I’ll want to do other stuff too – like serialize the objects in an Undum/Vorple game and save the state in localStorage. That shouldn’t be too difficult, but at the moment I wouldn’t even know where to start. Multiply that by a dozen different techniques, most of which I haven’t yet thought of…

Suggestions on how best to learn this stuff would be much appreciated!

Javascript is a small-ish language (which is widely supported) with a large set of APIs (which are inconsistently supported.) It sounds like you’re fairly comfortable with the language already.

The most important API is the DOM, but I don’t recommend you trying to learn it, at least not directly. Instead I suggest learning jQuery’s API. As well as smoothing out the browser differences it’s a good way to learn modern JS conventions - selecting elements by a CSS selector, modifying the page, and attaching events. You can do all of that through the DOM itself, it just takes more effort, and if you don’t use a library like jQuery or Prototype or Dojo or whatever you’ll inevitably start writing your own.

Then you’ll want to learn other APIs as you need them, maybe including Undum’s and Vorple’s. If you’re wanting to modify them you’ll need to learn not only how to use the code but the insides of the code itself. It will all be much of the same though, and they both use jQuery so they shouldn’t be too hard. Start by finding functions bound to the ready event - usually they are bound by giving a function directly to $(). Those functions will do everything that happens when you first open the page, after that you’ll need to find the functions bound to other events.

At a basic level, yes, and intellectually. For instance, I understand intellectually what a constructor function does, but I would have to wrack my brains for half an hour, and flip back and forth through a thousand-page book, to actually write one, and no idea at all why using a constructor would be the preferred approach in a given situation. I have close to zero practical experience, and no experience whatever with using Javascript to create a project of any complexity.

Understood … intellectually, and with qualifications. I mean, as far as I can tell, the DOM is just the standard list of HTML tags, which are arranged in a tree in the document. Or is there something about it that I don’t understand at all?

I’ve looked at jQuery, and I understand what you’re saying about how it streamlines the coding process and irons out browser differences. But trying to master jQuery is another whole layer on top of learning Javascript, so while I’m looking forward to it, I’m not sure I’m ready yet.

That’s where I’m getting lost (among other places). I have no idea what “bound” means in that context. I’ve only just learned about the ready event, and I would have to look it up again (somewhere or other) before I could use it. There are way too many questions! That’s the problem. I need a structured learning approach. Probably there’s a book that has such an approach, but I can’t afford to buy 20 books to find the one that’s right for me…

Jim, I’ve heard good things about this book, and a version of it is even available online for free,

eloquentjavascript.net/

Jim, you probably won’t ever need to mess around with constructors or prototypes or any of that. So if you can handle objects, arrays, strings, numbers and the operators that do stuff with them then you’re set. Next I really would recommend learning jQuery.

The DOM has elements, which have a tag name (for example

gets turned into a HTMLElement with a .tagname of ‘P’), properties, attributes (which are sometimes the same), and children. So I’d really recommend starting with jQuery to eliminate most of the mess. It’s quite simple. Essentially you select stuff, and then do stuff to them.

Selecting uses CSS selectors. So you could select all of the paragraphs $(‘p’), an element with an id $(’#header’), all the elements with a certain class $(’.small’), or a combination. $(‘p.note span’) will select all of the spans that are inside a paragraph with class note.

Then you do stuff to them.
$(‘p’).hide() will hide all the paragraphs,
$(’#header’).html(‘

new code’) will replace the header’s contents with the new code
$(’#header’).append(‘

new code’) will add the new code to the end of the header
$(’#header’).css(‘font-size’) will return the font size while $(’#header’).css(‘font-size’, ‘20px’) will set the font size

Events are trickier, but much the same. Select some elements and then attach an event handler. Maybe you could find some pdfs of jquery books before committing to buy one? There are a lot though and I haven’t read any.

Well, I have two or three specific things in mind. The first is, some sort of simple object-based world model. Undum’s model is strictly based on presentation of text, and while that works fine for CYOA narratives, the moment the author wants the reader to be able to pick up the rusty iron key in the scullery and use it on the oak door in the cellar, some sort of world model becomes pretty much a necessity.

Technically, you could do a certain amount by creating a player object and setting vorple.player.has_key to true or false. But that approach would, I think, become unwieldy before very long.

Second, serialization using JSON and localStorage. The save/restore mechanism used by Undum is not at all satisfactory. I emailed Ian Millington about this, and he seems not very interested in changing it, so I’ll need to write both code and a UI for it.

Third, an undo command. Ian’s reasoning for not allowing this, if I understand it correctly, is that in real life there is no undo. Time’s arrow can’t be reversed. (There are also some non-trivial questions about what would need to be done to the text output if Undo were implemented.) My view is that one of the reasons we enjoy playing IF is precisely that it’s better than real life, in that it allows us to try actions, observe the results, and then change our minds. So at least one level of Undo (if only to allow for an accidental click on the wrong link) would seem to be essential.

For all these reasons, I feel reluctant to use Undum/Vorple as is.

I suppose the best way to learn how to do this stuff might be to write a short Undum/Vorple story without worrying about any modifications, and then proceed to customize the code to add new features. But really, the nature of the story depends on the features available in the UI and in the code. If there’s no way for the player to pick up the rusty key in the scullery and carry it down to the cellar, that changes the story!

As a result, I’m sort of bumbling around, trying to figure out the best way to get the gold out of the gold mine when I don’t have a pick, a shovel, or a lantern.

Unless you’re wanting some sort of emergent system where the interactions between objects would be algorithmic rather than hand-coded you still shouldn’t need object oriented stuff in JS. If you’re set on undum then “qualities” might be what you want for simple inventory management (well for simple displaying of inventory.)

vorple is just an IO layer and the world model would remain in the virtual machine code.

Saves/restores/undos are another issue, but again they wouldn’t require object oriented JS.

I’m not sure what you’re envisioning when you say “emergent” and “algorithmic.” To me, it seems sensible that any in-story object that can change state should be represented by a code object. If the player can build a fire in the fireplace, then a fireplace object should be tested for the fire_laid and fire_burning properties. Trying to do it any other way would be messy.

The alternative employed by Undum is, I think, that when the player builds a fire in the fireplace the situation has changed. But that approach gets messy very quickly as more in-story state changes are added. It’s absurd to think that the drawing room is a different situation (for those who are unfamiliar with Undum, a “situation” is a block of code) when Aunt Beatrice is sitting in it than when Aunt Beatrice has gone upstairs. For one thing, if the fire is burning in the fireplace in the drawing room, we now have FOUR discrete situations to code – Beatrice+fire, Beatrice+!fire, !Beatrice+fire, and !Beatrice+!fire. That way lies madness. What one wants is an object-oriented world model in which each object (the fireplace, the drawing room, and Aunt Beatrice) keeps track of its own state and its own relation to the containment hierarchy.

I don’t think any of that is controversial. I’m a bit surprised that I even need to mention it.

Ultimately, I don’t have a problem with the standard world model as it is used in T3 and I6/7. I like it fine. What I don’t like is the 1980-era command-line parser. I feel strongly that the command-line parser is a dead end – a historical curiosity. When I bought my first computer (a Kaypro II) 30 years ago and a friend turned me on to Adventure, the command line was a state-of-the-art UI.

That was then. This is now.

Computer users today (that is to say, the huge potential audience for text-based interactive fiction) have an ENTIRELY different expectation of how to interact with the computer. They expect to point and click (or tap). They expect that the computer will respond with smoothly flowing JS-based design elements, even in a mostly-text environment such as a typical Web page.

The Undum/Vorple UI provides reader/players with a pleasant, modern experience. What I’m hoping to do, ultimately, is to graft that UI onto the IF world model. Discarding the world model strikes me as an excellent example of throwing the baby out with the bath water.

So I think I understand what you’re after: a hybrid system that looks like Undum but works like Vorple / WebUI, in the sense of wrapping around an I7 / T3 back-end that implements the world model.

I won’t say that’s what “everyone” wants but there are a fair number of people already in this camp. And probably everyone who owns a smartphone / tablet has thought, at one point or another, that IF would be really great on this device if it weren’t for all the typing.

My current angle is to reinvent adv3 without the parser and everything it implies. That’s not strictly necessary - one can imagine a WebUI remix with clickable links that delivered properly formed commands to the story file - but could have the virtue of making TADS far more accessible. There’s a lot of complexity that arises from verb rules, scope, and disambiguation; that complexity is essentially vestigial given a UI which presents a limited number of actions and a curated list of objects to act on.

Apart from slimming down adv3, there are other challenges. Do rooms / compass navigation still make sense? How should that be exposed in the UI? How are actions with one direct object handled? With a direct object + indirect object? Where does player inventory fit in?

I dislike the model where you click a hyperlink and then you get a list of actions that are relevant. This flips around the default IF interaction where I tend to think of a verb and then apply it to an object. I think I would prefer a set of interface buttons, one per action. When a button was pressed it would highlight / hyperlink the elements that were valid objects for that action.

But I won’t really know if I prefer that approach until I build a prototype and solicit feedback. That takes time and there are a lot of these experiments that could and should be tried. If you’re interested in that part, then JS / HTML / CSS are going to be a big part of your toolkit. You don’t have to make an attractive interface or even a working game; you just have to come up with a reasonable model and implement enough of it so that people can understand what you are proposing and decide if they like it.

I feel comfortable in saying that Undum is the wrong fit for an IF world model. It assumes a straight path from beginning to end; cycles in the output are handled poorly and if the player is flitting back and forth between rooms, that makes for a lot of cycles. Primarily this arises because of the transcript; perhaps the only workable approach is to jettison the transcript and give the player some other way of tracking state changes.

Meanwhile solves a similar problem by generating a high-level summary of story events. That strikes me as the most sensible way to go but it imposes a new cost on the author: for every piece of output, decide whether and how that output should be summarized at a higher level. TADS has something like this in the form of its transcript manipulation functions (mainReport, defaultReport, etc) and it’s reasonable to try to build on that foundation.

There are other parts of the problem space such as mobile app support that I won’t take up now. My point is just that this is the frontier of IF and there’s a lot of uncharted territory to cover.

Basically, yes. The attraction of Javascript is that what it looks like is, in the end, the author’s decision.

Mostly vestigial, yes … but not always. One might imagine, for instance, that the reader/player might want to turn on a lamp. This might be done either from a pop-up menu on the word “lamp” or from a sidebar menu of standard commands. And the lamp might not be plugged in, in which case some sort of check routine would still have to run. If the word “lamp” fails to highlight when the player clicks the “turn on” button, the player is liable to think it’s a bug in the game, rather than that the lamp is not plugged in or doesn’t have a bulb.

These are all very good questions. And different authors may have different answers, or even different answers when a given author is writing a different game.

A bigger challenge, I think, is how the game is to be delivered. One of the attractions of a strictly JS-based authoring system is that it runs in the browser. The moment you start talking about retaining the existing T3 engine, it has to run on a server, so (a) the author has to have a server, or access to one, (b) the game is likely to run more slowly due to communications delays, and won’t run at all without an Internet connection, and (c) the development of the authoring system requires a detailed understanding of PHP and stuff like that, which I know nothing about. Heck, I wouldn’t even have a clue how to write a T3 terp that would run on the desktop, let alone one that would use PHP to communicate with a remote client.

For all these reasons, a pure client-side system seems fairly attractive. To me, at least. I can at least envisage how to manufacture an object-based world model in JS, though it would take me quite a bit of time to get it up and running.

I like that idea.

Unfortunately, I’m not a real programmer, just a ham-handed amateur. All I really want is to write the content. But I also want my stories to be presented in an attractive, modern way, so I’m trying to jam a square peg (me) into a round hole (software development).

I suspect you’re right. I’m attracted to Undum because it actually exists and it looks nice.

Quest’s game UI is entirely HTML + JavaScript and I could certainly use a little help in making it look nice :slight_smile:

Right; I suppose I meant what you might call “grammar rules” instead of “action rules”. I would expect to be able to discard verify (aka “does the player mean”) but retain the equivalent of check / before / after rules in addition to the action code itself.

Well, I dodged the delivery question before under the guise of mobile app development. It’s not that it’s not an interesting or vital question; it’s just that I am fairly confident that any workable system with a web front-end could be deployed as a mobile app, and therefore the major barrier is coming up with a suitable UI.

Specifically in the context of T3, my thought is that a native iOS app could run the VM code in a background thread and the UI could be a web window talking to it over a local socket. I can’t say whether this is actually possible but it’s workable in theory. I’m willing to prioritize this effort should any really exciting interfaces appear in the T3 realm. The stock WebUI is OK, after some patches that will land in 3.1.1, but it’s not the sort of experience I would expect from an App Store purchase.

There is not really any PHP involved in the client/server communication in the T3 model. (It sees some use when deploying a public server, but it’s just basic glue code rather than anything essential.) The client is WebUI, written in HTML / CSS / JS. It communicates via AJAX with the web server - in this case a story file being run by the new VM which exposes networking capabilities.

Likewise there’s no need for authors to run a server; the gs.tads.io network is meant to solve that problem. It’s integrated into IFDB now but there’s ample capacity to handle growth and it’s trivial to make a new game available.

You might take another look at the T3 WebUI and see if you can extend it in ways that you find acceptable. That will probably be more straightforward than trying to hack a world model into Undum.

Another approach would be to adopt the role of project manager and outsource the front-end work after raising some money on Kickstarter.

I had a look. The documentation for the WebUI looks very sketchy to me. The section “Direct Javascript Programming” in the “The Web UI” page in the System Manual doesn’t tell the author how to do anything. The idea of customizing the WebUI is certainly tantalizing – but as a practical matter, doing so will only be possible if one studies a dozen different files of source code and puzzles out how they interact with one another to produce the visible output in the browser.

I mean, unless we can convince Eric to write a book about it. That would be nice.

Even if Eric were to write another book (not too likely), and even if someone like me were to read the book and then write a T3 extension that implemented a new UI at a basic level, the IF author who wanted to take advantage of such a game UI would still face two obstacles: (1) Workbench only runs in Windows; (2) TADS 3 seems to be rather intimidating to newcomers, even without the prospect of learning to use the WebUI.

I’ve written a couple of blog posts giving an overview of the situation as I see it:

midiguru.wordpress.com/stuck-in-lodi-again
midiguru.wordpress.com/look-through-telescope

Possibly these will stimulate some discussion. I’m going to cross-post these links to a new thread in this forum, rather than leave them tucked away in this thread. Comments are welcome!

It’s not documentation, but you can take a look at how my two WebUI extensions work:
dev.tads.io/t3ext/src/master/webui

WebUI is divided into a set of IFRAME windows - similar to the way banner windows worked in the bad old days before 3.1.

For practical purposes, each window needs three things:

  • An HTML file for WebUI to load as an IFRAME
  • A JavaScript file to handle functions for that window
  • A stanza in the T3 file to tell WebUI to load the new window

That stanza looks something like this:

/* this declares the WebWindow object for later use */
transient demoWin: WebWindow
	// vpath is where the browser sees the file
	vpath = '/demo.htm'
	// src is where the server finds the file
	src = 'webdemores/demo.htm'
;

/* this tells the server to allow access to content under the webdemores/ path */
WebResourceResFile
	vpath = static new RexPattern('/webdemores/')
;

/* initDisplay sets up the layout */
modify initDisplay() {
	// call the original initDisplay function to load the default layout
	replaced();

	// create our new window at x, y with width w and height h
	webMainWin.createFrame(demoWin, 'demo', '0, 0, 100%, 0');
}

If you look in your TADS install directory, you’ll find the files for the basic layout.

  • main.htm/css/js are the files for the overall window. This is where the new IFRAMES get attached.
  • statwin.htm/css/js are the files for the status window - the top bar.
  • cmdwin.htm/css/js are the files for the command buffer - where players type commands.
  • debuglog.htm/css/js are the files for the error console - you probably don’t care about this.
  • layoutwin.htm is kind of a generic version of main.htm - you can likely ignore it.

To do a full scale UI replacement, you would want to decide what windows you want to have, and modify the internal adv3 code to use those windows for output instead of cmdwin and statwin. Then you override initDisplay to load your windows instead of the regular set.

I am happy to assist and as long as we’re talking about TADS 3 / WebUI, I will even help you connect a mock interface to a story file template that makes use of your new layout.

Thanks. Could be interesting, but as you acknowledge, it’s not documentation.

In order to do that, I would need to read a thorough set of documentation. Better still, a detailed, step-by-step tutorial. I’m happy to admit that T3 may be able to do anything and everything I might envision – but I wouldn’t even know where to begin.

Let me think about that for a minute. Maybe we could start with the opening of “Mrs. Pepper’s Nasty Secret” (the stuff that happens before you get into the house, and not including Eric’s newbie sensing mechanism).

The interface should look like Undum, complete with flowing text and disposable in-text links to objects that can be interacted with. Each linked word (or phrase) should have a pop-up menu that shows the commands that would be useful for that object – look at, pick up, and so on. Objects that are carried in inventory should be listed in a right-side sidebar, and each of them should, again, have a pop-up menu showing the potentially useful commands (examine, drop, and so on). With commands that require two nouns, a sub-menu to the left or right of the pop-up should appear with a scrolling list of all of the other objects in scope.

This is just a proof of concept. I’m not proposing to rewrite all of “Mrs. Pepper” in that form (though who knows, that might turn out to be worth doing). The passive-aggressive point that I’m hinting at in proposing this is, I suspect that creating such a mock interface would be more work than you really want to volunteer for.

Or perhaps not. Perhaps I’m not giving you enough credit. But in any event, I’m pretty sure that creating such an interface using the Web UI would be a ton of work – and as I said, I wouldn’t even know where to start, because the Web UI is not documented.

For an authoring system to be usable, it can’t be set up as, “Try to find an eager volunteer who will create the interface for you.” That’s not a viable path forward, and wouldn’t be even if the T3 community had a hundred times as many knowledgeable coders.

The reason I’m suggesting “Mrs. Pepper” is not vanity, but rather because the source code is publicly available, so anyone who wanted to could inspect both the original source and your modifications thereof, in order to get a better idea how to do it. Also, it’s not a terribly complex or tricky opening, though there are some distant-visible objects. And I know what’s going on in it, so I could point out potential pitfalls and check for bugs.

Footnote: The more I think about it, the less frivolous this proposal seems. I think I might actually be serious about it (and willing to roll up my sleeves and work hard on it, with your help). I mean, not that “Mrs. Pepper” is a shining example of IF, but it’s the right size, it was conceived from the beginning as a simple game that would instruct both new players and new authors – and most important, if we had a really good working example of how T3 can do this type of interface, I think it might spark some real interest among other authors.

I don’t think we disagree that creating the mock interface is the hard part. We may mean something different by “proof of concept” though.

WebUI doesn’t really enter into it; the challenge is 100% client side, browser-based development. It’s fine to point at Undum and say “just like this please” but Undum (deliberately) does not address the demands of the IF world model. So it’s not a suitable starting point except as a source for some very good design ideas.

I guess I misunderstood your intentions; I thought you were taking on the role of eager volunteer and wanted to know how to get started. The general answer is that it doesn’t matter; any suitable interface could be adapted to Vorple / WebUI / Quest / FyreVM / whatever.

I don’t think this is a T3 problem even if I cast it in those terms. It is a community problem and any solution would be helpful. Design a great interface using HTML / JS / CSS and the IF world will beat a path to your door.

Getting started would be nice. That’s the sticking point, though. I would need to read about 200 pages of “Learning the T3 WebUI” in order to get started. And somebody would have to write it before I could read it.

I’m not trying to be stubborn – honestly, I’m not. But right now I feel rather like a hungry man who has been given a can of pork and beans but has no can opener. All I can do is break my teeth on the can.

You don’t need to read about WebUI because you don’t actually need to talk to a story file if you’re just mocking up a layout. All you need are a few dozen lines of “lorem ipsum” pasted into the appropriate sections on your page.

Think of the story file as a text generation engine. You give it some input and it delivers some output. The nature of that input and what happens to the output are entirely in your hands. Given that, you can work just as easily from placeholder text.

Let me give you an example. Say you really like my idea of having text with no visible links. You want the relevant links to light up whenever the player clicks an action button that applies to that object. One way to accomplish this would be to have a hyperlink like this in the output:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. <a href="#" id="vestibulum" class="examine take">Vestibulum</a> diam ipsum, tincidunt ac convallis at, egestas interdum nisi.

Where “vestibulum” is a hyperlink and the default CSS rules would not show any decorations on this link. So what happens is that the player clicks the “Examine” button (or image, or hyperlink) and there’s a Javascript event handler attached to that button. That calls a function which walks through the DOM and finds all “a” elements. If the element is of class “examine”, its style rules are rewritten so the link becomes active. If it’s not, they’re rewritten so it gets hidden again.

So where does the story file come in? Essentially for your interface to work, you’re counting on objects which respond to examine commands to show up in the output with the correct class list - so that your JavaScript function has something to key in on. Same deal for objects you can take.

Plus, if an object you can take shows up in the Inventory window, the game engine has to be smart enough to give it the “drop” class in place of “take”. (Assuming you want to model inventory at all!)

The part that you’re hung up on - the WebUI internal stuff - is just plumbing. All it does is send output from the game to the browser, and receive input from the browser to the game.

Sending input back is trivial from a browser standpoint, you are just saying, “hey the player clicked this thing, tell me what to print now”. Getting output from the game is likewise trivial; the trick is specifying how the game should send it. There are countless ways to format and structure the output and it all depends on what you want to do with it.

In the example above, I don’t need any kind of server or game engine to experiment with my UI. I just need to write some JavaScript that does the right thing when running on that chunk of static HTML.