Scenes and Stages, Continued

OK, so let's explain what those classes are about: I appreciate this is all deadly dull stuff - my apologies to anyone who came here expecting to find boobies. Anyway...

Scene: A scene is the entirety of an ADV sequence. From the initial message right up until the game returns to the usual management screens.

• The name field is the name of the scene. This will probably be used to look up the scene internally, and so should be unique in the game
• The narratives field is a hash table of Narrative objects. More about them in a moment
• The default field is the name of the default narrative; the one which would usually start the scene.

Narrative: A narrative is a series of snippets, images, funcs and headings. A narrative will usually be terminated by a Choice, or  by the end of the scene

• The name field is the narrative name. It is used to index the narratives by scene, and should be unique within a scene.
• The items field is an array of narrative items: snippets, images, etc, etc.

The Narrative items should probably all have a common super-class, probably called NarrativeItem. I haven't created one, because of the way Lua handles objects. On the one hand, sub-classing and polymorphism is possible but painful in Lua, and I'd prefer to avoid it. on the other hand, it's also unnecessary here, since Lua's object model is a lot more flexible than many.

Anyway, let's look at the narrative item classes.

Snippet: represents one message box worth of monologue or dialogue. The basic building blocks of any adventure game.

• The type field is always "snippet". This field is held in common with all the other narrative item classes, and is used to for a sort of half-baked pseudo-polymorphism internally. It's still easier than implementing full inheritance in Lua
• The cut field tells the engine to temporarily drop out of the processing loop and back into the C++ engine. This is so images and menus can be displayed correctly.
• text is the message to be displayed
• image is obsolete. It was intended to change the background image, prior to the image class

Image: Changes the background image of the display. Possibly more usefully named "background".

• type is always "image" It's a type discriminator field
• path is the path to the image, relative to the application root.

Func: Lets the user define a block of Lua code to run when the item is processed.

• type is always "func"
• code is a block of Lua code. 

The code section can do anything, but is probably most useful for setting flags to be tested later in the scene

          userdata.flag1 = true
    userdata.flag2 = false

The userdata table is part of the Narrator class, forced into global scope for the Func code.  One caveat: don't do this:

          function set_flags()
        userdata.flag1 = true
        userdata.flag2 = false
    end

If you do, the function will be defined, but never called, which probably isn't what you want.

Heading: This tells the engine to display a chapter heading that sets the scene for the exchange to follow.

• type is always "heading"
• text is the heading text. "Waking up is hard to do" for instance.
• timeout_ms is the timeout in milliseconds before the heading screen is removed. Default is 5000, or 5 seconds
• image is a background image to go with the caption.The plan was originally to overlay a translucent black layer on the opening image of the next scene, but I couldn'd make that work. This would give a way to achieve the same effect - but it's not implemented. Mainly because I think the black background works well enough.

Thumbnail: This displays a thumbnail sized image to the left or to the right of the text box. It's intended to show the speaker in dialogue. Coloured text would help as well. Not impmeneted yet.

• type is always "thumbnail"
• image is the path of the thumnail image, relative to the application root
• location is "left" or "right" and defines the side of the text box on which the image will appear
• operation is "show" or "hide". Thumbnails, once shown will remain visible until hidden.

Right.That's it for the classes. Next I need to talk about the classes that play this data, and about the XML format that we use to define scenes

Option: This is basically one menu item.

• text is the menu test to display
• next is the name of the narrative to start if this option is taken