Multiple Multi-Purpose Story Maps (high-concept feature proposal with story spec changes)

It's been awhile since I last proposed a "multiple story maps", "map folders" or "map pages" feature. Since then, my thinking has shifted. I realised I don't want "map pages" which are just the same story map split into multiple pages. What I want is something much more versatile. Something much closer to spreadsheet pages.

A rethinking of what passage coordinates actually mean.

This feature reconsiders one of the assumptions of Twine's story data format: that coordinates are inherent to passages. Once this notion is removed, one can ask powerful questions: aren't the coordinates just a way of visualising passages' relationships? And can't passages have multiple relationships to each other along different axes? Their authorship, their writing progress, their code vs. prose ratio, the spatial relationship of the prose settings, the characters' relationships, and so on? This feature realises these multiple dimensions of passage relationships, and reaches a succinct conclusion: it should be possible to make and use multiple maps using the exact same passages.

Thus: the Story Map is now a set of mappings (hence the name) of passages to coordinates (plus zoom level and other QOL stuff). Coordinates belong to the map, not passages in and of themselves. Each story map is a separate "view" into the story data, similar to how spreadsheets can present different "views" of the same basic rows.

Feature: Not every passage needs to be in every story map.

One of the big reasons I want this feature is to allow separate story maps for entire chapters of a story. Rather than having to lay out the entire story in a single canvas, relying on the distance between clumps of passages to indicate structure, that structure can be made very explicit by creating multiple maps, and only placing certain chapters' passages in each map.

Feature: The same passages can be arranged in different locations and structures in different maps.

Each Story Map can thus have a different use, a different meaning. Consider the following story map purposes:

A map for all of the "utility" passages (with custom macros, headers, et cetera) separate from the "actual prose" of the story.
A map with all passages arranged in "finished" vs. "draft" columns, as an alternative to tagging.
(Using Harlowe storylets) a map for all of the storylets in a particular story - note that the storylet design pattern's major advantage is being able to add or remove storylets at will without needing to alter the passages that "connect" to them, because their connections are constraints rather than specific links.

With this feature, you can have all three at once.

The "Drawer", a UI element where passages go when they aren't in the current map.

Passages that don't appear in the current map can be added by dragging them out of the Drawer, which is an element (I imagine it as a scrolling UI "tray" element) that sits beneath or to the left of each map. When a passage is created, it appears in the current map, but can be moved off the map by dragging it to the Drawer. This continues to use the "drag and drop" interaction language of the map itself.

It is possible for a passage to be left in the Drawer, and appear in no maps. This offers an alternative way to remove passages from the visible workarea without actually deleting them. Since deletion is permanent, this can serve as a middle ground while you deliberate on whether you truly want to delete said passage or not.

What it means for twine-2-htmloutput-spec.md

https://github.com/iftechfoundation/twine-specs/blob/master/twine-2-htmloutput-spec.md

Basically, it means the addition of the following elements inside <tw-storydata>: many <tw-storymap> elements which have names, orderings (in a storymap list), and zoom, and they each have <tw-passagecell> elements which are a mapping of passage → position.

<tw-storymap
    order="1"
    name="Chapter 1"
    zoom=1.2
    >
    ...
    <tw-passagecell
        pid="14"
        position="102,99"
        size="100,100">
    ...
</tw-storymap>
...

Also, <tw-passage> elements would no longer have position or size attributes, and <tw-storydata> no longer has zoom.

Interpretation of the existing position data for passages

When importing a story from a version without <tw-storymap> elements, then one is created, given a default name (like "Story Map"), given a zoom attr from <tw-storydata>, then, for each passage, a <tw-passagecell> is created that has the passage's pid, position and size.

Obvious question

Q. What does a link arrow look like when it points to a passage not on the current map? A. I envision an arrow terminating at a name, similar to the current broken-link arrow.

Conclusion

I think this is the best way to implement multiple story maps. It allows them to be used in multiple versatile ways, reflecting the many stages of design/writing/reviewing/structuring that authoring can take, and, by not tying them to the existence of passages, lets them be "lightweight" and easily duplicated, modified, etc. Some of the nitty-gritty details (such as the shape and interaction of the "Drawer") are up for debate, but I think the core idea outlined in the first section of this post is rock solid.

I will help implement this if you think approvingly of it.

Presubmission checklist

[X] I am interested in working on code that would implement this feature request. (This is not required to submit a suggestion.)
[X] I have done a search and believe that an issue does not already exist for this idea in the GitHub repository.
[X] I have read and agree to abide by this project's Code of Conduct.

You are basically describing the Model and View components of a Model View Controller architectural pattern, where a set of Passages (the Model) can appear within multiple Story Maps (the Views).

How do you perceive your proposed restructure will affected a TWEE Notation based project? How will such a project influence the creation of one or more Story Maps?

You are basically describing the Model and View components of a Model View Controller architectural pattern, where a set of Passages (the Model) can appear within multiple Story Maps (the Views).

The term MVC by itself doesn't imply a one-to-many relation between models and views… the current Twine app is an MVC app (in React), only currently having one story map view to the passage data model.

How do you perceive your proposed restructure will affected a TWEE Notation based project? How will such a project influence the creation of one or more Story Maps?

Well, if the project is using on-spec Twee, then all of the story map-related properties are optional, right? When importing, it should follow the same principles as above (when creating a default storymap, for each passage, a <tw-passagecell> is created that has the passage's pid, position and size) and any absences of values are handled as they are by the current Twine app. Not sure if that's what you mean to ask.

My interpretation of @greyelf's question about Twee is how would you represent the mutiple story-views in a Twee file.

Twee notation files are currently able to entirely represent the structure of a Twine story file, and vice-versa, and a large portion of the Twine community currently works in twee notation (using tweego, or some other compiler, and optionally representing the story using some other visualiser — e.g. T3LT). I think there are strong arguments for retaining that interoperability, so that raises the question of how to represent that data in a Twee file.

So what should the export of a Twine file with multiple story views to Twee look like? Would there need to be a Twee4 spec? How should story viewers that don't use multiple passage maps represent that data?

On a different note, I would see this as yet another expression of the desire behind the request for story map comments, story map coloured rectangles, story map folders, and so forth — the feeling that we cannot currently adequately express the story structure on the map using placement of passages alone, or that doing so is onerous.

@hituro You interpreted my possibly badly worded questions correctly.

That any Twee compiler that can decompile/export the contents of a Story/Project HTML file needs to know what it does with the Story Maps meta-data. eg. Does it get added to the contents of the StoryData special Passage? Does it cause the creation of "child" folders in the target output location, with each direct "child" folder representing a specific Story Map; etc...

And how does an existing Twee based project generate the new Story Maps meta-data?

One possible solution for a Twee based project, other that its Developer manually editing a Story Maps structure, would be for each direct child folder of the "source" structure to be treated as an individual Story Map, with the file content of the root/parent folder itself being part of the "main" Story Map.

eg. If the Twee project folder structure looks something like...

c:\adventure\
    dist\
        media\
            forest.jpg
        adventure.html
    src\
        folder1\
            file1.tw
            file2.tw
        folder2\
            file3.tw
            file4.tw
        modules\
            inventory.tw
        main.tw
        setup.tw

note: The above is a contrived structure, I am not suggesting that it is one that a Twee Developer should be using!

Then the Passages within the main.tw and setup.tw files located in the src folder would be placed within the "main" Story Map, the Passages stored in the tw files of the folder1 folder would be another Story Map, and so on for the folder2 & modules folders.

Thus the generated Story HTML file would contain the meta-data of four Story Maps.

First, setting expectations... I think multiple sheets or whatever we end up calling them will be something that I want to tackle in 2.8. There's a 2.6.1 underway and I have some thoughts on what I want to focus on for 2.7 (mostly app-specific changes, like exploring whether we can allow people to choose a different story library location, since that has been a frequent request).

I've been thinking about this idea for a while now and right now, I think I'm put off by the level of complexity that would be added here. We would need to teach users what the Drawer's purpose was, and that passages might be in there (if they're not in the current story map) or not (if they are). We would need to make the Drawer navigable--quite a few passages might end up there. We would also need to teach users that there's a difference between removing a passage from a story map and permanently deleting it, and that changing most things about a passage (its text, tags, etc) affect story maps not in view.

The spreadsheet metaphor isn't a 1:1 match to what you're proposing, and I think that's where I'm having trouble. The other metaphor that comes to mind is the idea of file shortcuts (in Windows) or aliases (on Macs). In both spreadsheet references and aliases/shortcuts, there's always a source item. You can have cell D4 on Sheet 1 reference cell A1 on Sheet 2, but changing D4 doesn't change A1.

Right now, my opinion is that's important that passages exist in one place and one place only.

For what it's worth, though it's early days for my own thinking on this, my own thoughts have run toward whether maps should exist like spreadsheet sheets, with a row of tabs running at the bottom, or whether they should be items you can move around and nest in the story map, like folders (which you mentioned proposing in the past). Right now I think folders are the more powerful concept, since they'd allow multiple nesting levels, and they probably mesh better with Twine's spatial nature. But they also are of course harder to implement and it would be possible for users to lose things five levels deep.

@klembot For my own use — and I can't claim to be representative — the key issue is that as a story grows more complex it becomes hard to group passages visually on the map in a way that reflects the divisions of the story, whether it is a group that relates to a storyline, or a location, or a gameplay unit. In general we must do this by leaving space between groups of passages, or leaning on the tag colours to try and distinguish one blob from another.

Having said that, I think the single story map is a powerful feature. The very fact that we can (to some extent) succeed in structuring things with the very basic tools available, is a testament to the power of the map metaphor. It works, but it struggles as the story gets larger and the units more complex. I feel that any enhancement shouldn't lose the power of the map that we already have.

If it were me, I'd be wary of drawers, or tabs, or anything that makes the map metaphor itself weaker. "pro" users, working with tweego and VSC, may not care for it, but passage arrows and groups of passages are the building blocks for most users.

My own suggestion — some sort of coloured boxes with labels — was of this sort, an enhancement that didn't fundamentally change the visual metaphor being used. I think you'd get the same sort of enhancement from the ability to highlight all passages using a tag, or from more tag colours, or from bolder tag indicators (e.g. colouring the entire passage box), and the like. If you want to "collapse" passages into a box or folder (perhaps with many arrows coming in and out, it should collapse in place on the map, because only that doesn't break the metaphor — that sort of thing.

@hituro A couple thoughts...

It's important to me that if this is implemented, it's done in a way that people can ignore if they don't want to use it.
Besides organization, the other big reason for a sheet or some other division is performance. I spent a lot of time in 2.4 trying to optimize for large stories, but my impression is that although I've raised the ceiling on viable story size, it's still present. Allowing people to split up stories into sections of some kind would solve these performance issues.

klembot / twinejs