Tightly Interconnected Code

I have been reluctant to work on Siboot for the last few days, taking advantage of every opportunity to put it off. This morning I faced myself squarely and asked myself why I was not working on Siboot. The answer, it turns out, is that I’m scared to work on it. I’m afraid that I’ll get lost in the complexity. It was all so easy at the outset, when there weren’t many verbs, but now Siboot has 43 Verbs, about 800 scripts, and it’s getting complicated. 

I recognize that this is precisely the same problem that I experienced with all the other storyworlds I have attempted to build. It reaches a certain level of complexity and I start flailing around, writing scripts and then throwing them out, making little forward progress.

In some ways this is similar to the classic problem of complexity that has bedeviled programming for decades, and has been the inspiration for many new programming languages. Back in the old days, programs written in BASIC were renowned for “spaghetti code”: code that jumped all over the place, making it almost impossible to trace, or to track down bugs. 

The first response to this was an idea called “structured programming”, best embodied in the Pascal language. Such languages imposed strict constraints on the programmer, eliminating the GOTO statement and requiring that all routines communicate with each other through a standard system. Global variables were much frowned upon, but we still used a lot of global variables.

The next big idea was ‘object-oriented programming’, in which data and routines were grouped together in a tight format that kept different parts of the program well-separated. C++ is the most commonly used form of this, but it’s a bit of a hack and doesn’t embody object-oriented principles well. Java, on the other hand, does a good job of embodying the ideas of object-oriented programming.

With these experiences in mind, do I need to move my scripting system (“Sappho”) to something more structured, or something more object-oriented? No, that’s not the right way to think about the problem, because Sappho is already high structured and highly object-oriented. Each Verb, Role, and Option has defined scripts attached to it, and the scripts are tightly constrained to follow a narrow pattern. Likewise, the system is broken down into a hierarchy of objects: Verbs, Roles, and Options, each of which has its own methods (scripts) and data (called “boxes”). There are a few global items: some global boxes for global variables, and global scripts that can be used anywhere, rather like operating system utility subroutines.

No, what scares me so much is the sense that I’m coding in the dark, that when I write one script, I don’t have a good idea of what similar scripts look like. I fear that there’s something out there that will cause some sort of jam. 

The reason I have this sensation of groping in the dark can be explained with a deeper examination of the problem. It’s what I call “tightly interconnected code”. Consider the structure of a typical scientific program:

Scientific program

Note how neat everything is; each unit in the program interacts with just two other units (three for the “Finished” unit). A typical commercial program is much more complicated than this, but architecturally, most units in the program interact with very few other units. If there is a unit that interacts with many other units, it is set up as a special “library routine” and given precise input-output specifications. The system remains fairly neat. It can be huge, of course, but when writing any particular part of the program, you needn’t worry much about other parts of the program. 

Not so interactive storyworlds; the whole point of a storyworld is to weave the verbs together so tightly that the developing story can go in many different directions. The architecture of a storyworld should look more like this:


This reveals the central problem: when you’re writing scripts, it’s difficult to anticipate what verbs might connect to the verb you’re working on, either as input or output. You could write scripts with assumptions based on the existing set of connections, but what if you add a new connection later on? That could screw up everything. 

What I need is an organizational document that I could consult while working on the storyworld. Here are two possible schemes:

1. Verb-centered. This would look rather like the rehearsal diagram already available in SWAT:


I could use such a diagram to look up relationships; perhaps that would help. But this seems clumsy.

2. Cluster diagrams We had the idea for clusters many years ago, and I actually implemented it in Erasmatron 3.0. The basic idea is that verbs are organized into clusters that have defined entry and exit points. A cluster diagram looks like this:

The two verbs on the left are outside the cluster; not shown are the verbs that can lead into the cluster. The consequences of the various ‘plan’ verbs are also not shown.

The entire storyworld would then be presented as a collection of clusters, like so:

Storyworld Structure

Will a diagram like this be sufficient to guide my coding? Will it give me enough confidence to proceed with scripting? Does it need to be enhanced with additional information?

I decided to try it out and see what I got. Here are the three spaghetti diagrams I produced for the core parts of the storyworld so far:

Conversation Cluster
Deal Cluster
Threat Cluster

You know, I think these spaghetti diagrams really do help me visualize the system. I’ll do some more work refining them then start applying them to the verbs in the storyworld.