draft

Readme.md

@@ -1,2 +1,3 @@
+* `spec.md` specs of the framework
 * `engine.toml` model definition of the engine
 * `database.toml` (planned) schema description of the evaluation database

engine.toml

@@ -5,22 +5,17 @@ spaces = [] # a room must have at least one space
 [space]
 id = 2
 size = [2, 4]
-doors = [] # a space has at least one entrance and one exit to other spaces either within the same room or from/to another room
+passages = [] # a space may contain passages to other spaces
 modules = [] # a space may have modules
 
 [passage]
 id = 3
-exit = 4 # the exit door of this passage
+exit = "Door Module A" # the exit of this passage
-entry = 5 # the entry door of this passage
+entry = "Door Module B" # the entry of this passage
 type = "portal" # elevator, moving platform, etc.
 
-[door]
-id = 4
-passage = 3
-
 [module]
 name = "Module A"
-size = [1, 1]
 position = [0, 1]
 rotation = 90
 types = [] # a module must have at least one type
@@ -29,30 +24,45 @@ time-estimation = 342 # estimated amount of seconds to complete this puzzle
 requirements = [] # a module may have requirements
 
 [[types]]
-description = "dexterity"
+description = "door"
 [[types]]
-description = "precision"
+description = "puzzle/dexterity"
 [[types]]
-description = "combination"
+description = "puzzle/precision"
 [[types]]
-description = "iteration"
+description = "puzzle/combination"
+[[types]]
+description = "puzzle/iteration"
 
 [[requirements]]
-name = "minimum space"
+name = "area"
+size = [1, 1]
 [[requirements]]
-name = "connected module" # in the same room as another module
+name = "space size"
-module = "Module B"
+size = [4, 2]
-[[requirements]]
-name = "object" # an object is required to be posessed
-provided = false # whether this module provides this object itself
 [[requirements]]
 name = "space around" # space that is not directly occupied by the module but must be available
+size = [2, 2]
+[[requirements]]
+name = "existence" # in the same room as another module
+module = "Module B"
+where = "current" # current: in this space, anywhere: in this space or any previously visited space
 [[requirements]]
 name = "facing" # must be facing another module
 module = "Module B"
 type = "exact" # exact: exactly opposite of, raycast: must be visible from
 [[requirements]]
-name = "minimum space size"
+name = "object" # an object is required to be posessed
+provided = false # whether this module provides this object itself
+
+[[relations]] # a collection relation with an arbitrary number of modules
+name = "paintings"
+modules = []
+[[relations]] # a group relation with named modules
+name = "Puzzle A"
+crank = "Crank Module A"
+balloon = "Balloon Module B"
+hint = "Hidden Module C"
 
 [object]
 name = "Object A"

spec.md

@@ -0,0 +1,107 @@
+# Modular Room Design Framework (name pending)
+
+A design framework for modular VR experiences.
+
+> **WORK IN PROGRESS**: *This document is a work in progress. Expect major changes.*
+
+## Objectives
+Many virtual reality experiences take place in a series of rooms. In comparison to room-based physical experiences (think of escape rooms or museums), VR offers the possibility to adjust future rooms and layouts on the fly to the needs of the user, or other criteria. To make this possible, rooms and the modules therein must be designed in a way that allows them to be adjusted to the requirements of the specific application.
+
+This specification aims to be a framework for modular room design in virtual reality.
+
+## Nomenclature
+
+### Engine
+This framework is made to guide the implementation of room-based VR applications that adjust the experience to the user while they are in it. In this document, we will call these applications the engine.
+
+### Experience
+The experience is the VR application that the user runs. It is generated by the engine out of random and modular parts.
+
+An experience can have several goals, be they recreational, educational or otherwise.
+
+> TODO: Introduce a running example
+
+---
+
+## Table of Contents
+<!-- MarkdownTOC autolink=true -->
+
+- [Measuring](#measuring)
+- [Rooms](#rooms)
+- [Spaces](#spaces)
+- [Modules](#modules)
+- [Module Variants](#module-variants)
+- [Passages](#passages)
+- [Type](#type)
+- [Requirements](#requirements)
+- [Relations](#relations)
+- [Objects](#objects)
+
+<!-- /MarkdownTOC -->
+
+## Measuring
+For the engine to dynamically adapt to the user, it needs measures by which it can decide how to change the experience.
+
+> TODO: decide which one of the following examples to keep
+
+An example for such a measure could be how much the user looks at paintings of a specific time period in a museum and adjust future rooms to contain more paintings of that period to tend to the user's interests. Or, conversely, that time period could be avoided to increase the diversity of art the user sees.
+
+An example for such a measure could be how long the user takes to solve puzzles in an escape room and adjust future rooms to contain more puzzles of a difficulty level appropriate for the user.
+
+## Rooms
+A room is the abstract definition of a location that the user can find themselves in. It contains a physical representation of the room, a group of [spaces](#spaces), and any number of [modules](#modules).
+
+Rooms that have not yet been visited can be dynamically created and adjusted to fit the measures of the currently running experience or recorded measures from past experiences. As soon as a room is available to be accessed by the user, it should not be fundamentally changed anymore.
+
+Rooms themselves do not tell anything about their physical representation, but they must consist of at least one space that does.
+
+## Spaces
+The physical representation of rooms is contained in a space or a group of spaces. They provide a physical layout, a polygon that defines the ground plan of the space. Generally, it is advisable to restrict the layout of spaces to the physical space available to the engine, which is normally a rectangle.
+
+A space may contain multiple [modules](#modules).
+
+## Modules
+A module is an arbitrary, self-contained element. It is placed in a space by the engine according to measures and possible [requirements](#requirements) to ensure a module is only used the way it was intended to be used.
+
+Modules have one or more [types](#type) that help the engine distinguish them. Two or more modules may be [related](#relations). Finally, modules may contain or provide any number of [objects](#objects).
+
+Examples for elements are a painting on a wall or a puzzle in an escape room.
+
+## Module Variants
+
+> TODO: A module can have variants of different sizes, with slightly differing properties, etc.
+
+## Passages
+Spaces can be connected to other spaces within the current room or spaces in other rooms. A passage consists of two doors, which themselves are a module in a space.
+
+Passages can be simple doors, moving platforms, elevators or anything else transporting the user between spaces.
+
+## Type
+Module types give a high-level description of a module. They may be used by the engine to distinguish different modules either for the purpose of choosing and placing them or to find the right measures to analyse them.
+
+Types can be defined as a flat list of strings if they don't have any correlation. Otherwise, they should be in a tree structure formatted like `parent-type/child-type`.
+
+One example module type that is used when building spaces was already introduced earlier: The door module. Other examples might be used when measuring the interactions with puzzle modules. These could be types like "dexterity", "precision" or "combination".
+
+Depending on the use case, there could be different kinds of doors, e.g. "door/simple", "door/teleporter-exit", "door/teleporter-entry".
+
+## Requirements
+Modules may have certain restrictions on how they should be used by the engine. Requirements exactly specify these restrictions.
+
+- **Area requirement**: This requirement should be present on most modules. It defines the area of a space a module needs to fit.
+- **Space size requirement**: This requirement defines a required size the space must have.
+- **Existence requirement**: This requirement forces the existence of another module in a room that is accessible to the user.
+- **Facing requirement**: This requirement forces another module to be placed either directly opposite of this one or visible from it.
+- **Object requirement**: This requirement lists one or more objects that the user is either required to alerady be in posession of or that must be obtainable in the same room as this module.
+
+The facing requirement is a strictly stronger requirement to the existence requirement. The space size requirement is useful to prevent large modules from filling up small spaces.
+
+## Relations
+Multiple modules that form a logical union without necessarily being positioned together should be defined by a relation. The relation does not impose any restrictions on the modules, it simply allows the modules to be aware of each other. If a module needs its related modules to exist in the same space or room, an existence requirement should be used.
+
+Relations may be used with a specific number of modules. Alternatively, they can combine an arbitrary number of similar or equal modules into one bucket. These types of relations are called group relations or collection relations respectively.
+
+Related modules could for example be parts of a single puzzle that are placed separately from each other in an escape room.
+
+## Objects
+> TODO