This document outlines the development of OpenMW after the 1.0 release.
For the first couple of feature releases after 1.0 we should focus on giving mod developers additional tools so they can produce interesting mods with features not supported in vanilla Morrowind. If we look at the use of Morrowind (e.g. on Twitch) we see that people still overwhelmingly make use of the vanilla engine instead of OpenMW. We want to make OpenMW the default choice when playing Morrowind-content. The way to achieve this goal are interesting and desirable mods that require OpenMW.
Now is not the time for sweeping architectural changes. With 1.0 we acquired an enormous advantage over vanilla Morrowind (full source access) and now we should cash in on that advantage by pushing out large numbers of features that are directly visible to the user.
At the same time we want to stay true to our origins. While we want to broaden the scope of OpenMW and make it into a more general purpose engine (in the sense that it is used for more than just playing Morrowind), it should still be a Morrowindesque engine. The general direction should be to widen and to generalise. We aim to evolve, not to revolutionise.
Our goal here is to make OpenMW into a general purpose engine, but a general purpose 1st/3rd person real-time RPG engine. We do not attempt to support other genres or other flavours of RPG.
The development of OpenMW will hopefully continue for a long time and we can not reasonably hope to sketch out its entire future development in a single design document. Therefore this document should be seen as stage 1 of the post 1.0 development only. It may last us 6 months or a year or several years, depending on how much development activity we can achieve. But eventually there will be a stage 2 design document.
The terminology regarding instances and objects is somewhat confusing since there are several variants of it that are incompatible with each other. Throughout this document we will use the following variant:
* Instance: The sub-records placed within a cell record. Mostly called references in the vanilla Morrowind terminology. In C++ OOP we would rather call this an object or an instance.
* Object: Records like doors, activators, containers and so on. Mostly called IDs in the vanilla Morrowind terminology. In C++ OOP we would rather call this a class.
In a few cases the term "object" will be used in the classical OOP sense. Any such mentioning will be accompanied by a statement about the different use.
## Deprecation
This document declares some features and functions as deprecated. This usage is somewhat different from the usual meaning in software development. Usually something being deprecated not only means that its use is discouraged but also that it may be removed in later versions. In OpenMW we can not ever do the later because that would break compatibility with older content.
Instead a feature being deprecated shall mean the following:
* We discourage the use of the feature (and may reinforce this position by non-intrusive warning messages at some point)
* We will not extend the feature to work with other enhancements of OpenMW.
A hypothetical example: We deprecate the MessageBox instruction. If we introduce new variable types, the MessageBox text formatting will not be extended to cover these.
## Script Instructions and Script Functions
We define a script instruction as a statement that does not have any return value and therefore can't be used as part of an expression. We define script functions as a function that does have a return value. Sometimes the term script instruction is used to mean both instructions and functions (since we do not have a term that covers both).
We also use the term script function for user defined scripts that are used as functions.
The meaning should be clear from context.
# Organisation & Procedures
This document describes the core enhancements for the next couple of feature releases after 1.0. This does not mean that these releases are limited to what is described here. We have a whole feature request forum full of ideas and many issues on the bug-tracker. But we need to be careful here about what we add and what not.
With 1.0 we have a clear goal in front of us. After 1.0 things are less clear. We need to consider that any feature we add now and that influences the file formats will stay forever. We can not ever remove features of this kind because that would break compatibility with older content files. Even with features that don't influence the file format we should consider carefully so the engine does not end up as a bloated mess.
## Versioning
We continue with the semantic versioning scheme, meaning the next feature releases will be 1.1.0, 1.2.0, 1.3.0 and so on.
We will only jump to 2.0.0 if a fundamental change is made (e.g. multiplayer). Otherwise we will continue, even if that means we end up with version 1.314159.0 eventually.
OpenMW and OpenMW-CS will be kept in sync after 1.0.
**Important**: If OpenMW reaches 1.0 before OpenMW-CS, we need to wait for OpenMW-CS to catch up before we continue with feature development.
## Bug Fix Releases
We may decide to have regular bug fix releases in parallel to the feature release development, i.e. while we work on 1.2.0 there could be 1.1.1, 1.1.2, 1.1.3 and so on. If OpenMW is adopted more widely and the development of feature releases takes a longer time this approach might be beneficial to the end users. We would then continue to develop on the release branch of the feature release which then becomes a maintenance branch. This could either happen via (i) merging bug fix commits into the maintenance branch and then periodically merge the maintenance branch into master or (ii) merge bug fix commits both into the maintenance branch and master.
However this approach means additional work and would be of limited usefulness if we have very quick feature releases. We should hear the people involved in the release process on this topic before we make a decision, because they would be the ones having to do most of the additional work.
We will continue with the revised roadmap scheme. This means we add a new label (stage1). After we are finished discussing this design document and have made necessary adjustments we will cut it up into individual tasks and add them to the tracker with the stage1 label. This label will then take the role of the current 1.0 label.
Confirmed bug reports also get tagged with stage1. Other issues (feature requests and tasks) only after we have approved them for near future development.
We will most likely not have a separate stage1 label for the editor, since for the bulk of the changes (The Grand De-hardcoding) most tasks we will require changes to both OpenMW and the editor.
We will continue with the same general structure of the content file format. All changes will be specific to individual record types.
We already have a new version counter in the omwaddon and omwgame file formats. We will continue to increase this counter with every new feature release that requires additions or modifications to the file format.
The ability to read files of older formats must be maintained. The ability of the editor to write older file formats is optional and unless there is strong demand and enough manpower we will most like not support this feature.
## Records
Records from older file formats are adjusted and converted during the load process (both in OpenMW and OpenMW-CS). The data structures in OpenMW and OpenMW-CS will always match the most up to date version.
The following cases of changes to the record format have been identified:
* New optional records: No action on load required since the older formats won't have this kind of record.
* New mandatory records: Records are build from cfg values or/and GMST values. Typically such a record will merge several values from these sources. We create these records only if the omwgame file is of a version prior to the introduction of this record. We need to modify the record when omwaddon files provide their own record for the value sources (i.e. GMST records).
* Existing records with new optional fields: No action on load required. We already support this.
* Existing records with new mandatory fields: Same as with new mandatory records.
* Existing record that needs to be fully converted into a different record type: Conversion needs to be performed on load.
* Existing record that is switched over from integer-based to ID-based indexing (this is a special case of the case above)
* Existing records is split into two records: Split needs to be performed on load.
There have been some concerns regarding the efficiency of string based IDs (vs. integer). While there hasn't been an evidence indicating that this is actually a problem in OpenMW, it is important to point out that the move from integer to string does not mean that such a problem could not be addressed.
We already have plans to introduce a new string type for IDs, which deals with the case-issue (current std::string based implementation is error-prone and results in some very verbose code).
If we are careful when designing this new string class it will be easy to swap out the implementation from a string based one to an integer based one, where the actual strings are stored in a hash-table (similar to the FName class in Unreal Engine 4).
If we allow older format content files to depend on newer format content files the loading process will become more complicated (see the example given in the "New mandatory records" case). We could avoid these complications by forbidding content files from depending on content files with newer format. This limitation however would have a noticeable usability impact. This issue needs to be discussed further.
All new records will be identified by a unique string ID. We will not add any new record types that are indexed by integer values (e.g. skills) or other schemes. Descriptions of new record type in this document will usually leave out the ID field.
## Namespaces
Within the editor we already have limited pre-1.0 support for namespaces (using C++ syntax). We will continue to expand on that. Namespaces are case-insensitive.
Namespaces will serve as a tool to avoid naming conflicts between content files and to organise records within a content file.
We encourage a clean use of namespaces, meaning there will be no equivalent of 'using namespace'.
We will not enforce the use of a single namespace (not accounting for sub-namespaces) per content file. But we will strongly encourage this approach.
There are four special namespaces:
* sys: This is equivalent to std in C++. In general only we are allowed to add new IDs to it (e.g. new GMSTs).
* project: Records within this namespace are saved in a local project file, but may also be presented to OpenMW when starting it through OpenMW-CS.
* session: Records with this namespace exist only for the duration of a single editing sessions and are currently not presented to OpenMW.
* default: Previously called sys::default (see section about cells and worldspaces)
To encourage at least some degree of stylistic uniformity we will use only all lower case names for namespaces in all official documentation.
Having a record with the same ID as a namespace is allowed (see section about cells & worldspaces for an example).
# Meta-Data & File Management
## Identifying Meta-Data
Identifying meta-data specifies the identity of the content file in a formal way that can be utilised by various tools.
There are four parts to this meta data:
* Name: A unique name that identifies the content file across all versions and all languages
* Version: A unique version identifier. A uniform versioning scheme is required here to avoid unnecessary complexity in the tools. Most likely we will use the same semantic scheme as with OpenMW itself.
* Language: see section about localisation
* Multiplayer: see subsection about multiplayer in misc section
There are two possible ways to encode this meta data:
1. In a new record or sub-record
2. In the file name
The record option is more flexible and allows for extensions at a later point with the least amount of disruption. It also avoids unnecessarily cryptic file names. On the other hand we need unique file names anyway and storing the information in the file name avoids redundancy. This needs to be discussed further.
There is a large number of possible uses for this kind of meta data. Here are some examples:
* Simplifying the content file selection within the launcher: All entries for the same content file can be grouped into a single row. We can then add two columns for version and language that contain a combo box with the available options. That should reduce the amount of clutter significantly and also should help to avoid user errors because it is now impossible to select two versions of the same file at once.
* We can add a language setting to the launcher and make it automatically select the preferred language for content files (where available).
* Tools for porting content files from one version of a dependency to another will benefit from being able to automatically identify that two different dependencies are actually just different versions of the same file.
## Non-Identifying Meta-Data
### License
We provide the user with a reasonable list of license choices (including a custom one where the user can provide his own license text). When the content file is packaged by the editor, a copy of the license text is included automatically. For newly created content files this field should be set to a sensible default (definitely not custom). Furthermore the merge tool can check for possible license conflicts.
This enhancement will hopefully cut down on the license wild-growth within the Morrowind modding community. If we want to get fancy with this feature we could also add a tool that helps the user to decide on a license.
### List of Authors
Currently we have a single text field for the authors. This is suboptimal for community projects. With the current solution the best a community can do is to insert 'The x Team' and then maintain an external list.
A better solution is to replace this field with a list of names that can be automatically merged (including checking for duplicates) when merging content files.
The editor can be configured with a user name, which is automatically inserted when creating a new content file or modifying an existing content file.
## Resources Files
### Problem
Currently all resources files of all installed content files are dumped into a single directory. This poses several problems:
* A content file that comes with resources files that override other resources files can not be simple switched off by disabling it in the launcher.
* Without external record keeping there is no way of knowing which resources files to include when packaging a content file for release. This is a particularly big problem if we want to automate this process.
* Automated tools for checking for missing resources won't be able to look at the resources for the currently selected stack of content files only, which means some problems may remain undetected.
### Data Paths
Some people have started to put different content files into separate directories, each with its own data path. This is not a solution.
The selection of data path is a separate stage from the selection of content files. More precisely the available selection of content files depends on the selection of data paths. This results in a two stage content selection mechanism, which is undesirable from a usability perspective.
### Solution
The solution is to group resources files within the data directory structure.
The first proposed solution (putting all resources files into a single archive with the same name as the content file) received a lot of criticism during forum discussions.
As an alternative we could create a single content directory (per content file) within the data directory. This content directory would then contain the content file and the usual directory structure (Icons, Meshes, Music, ...).
We may offer one of these solutions or both. This needs to be discussed further.
In the forum the following flaw in the archive solution has been brought up (applies equally to the directory solution):
In some cases one may want to use only the resources from a content file without the actual content file and license reason may stop the repackaging in a form that allows this kind of usage within the new system.
There is an easy fix for this issue: We add a flag to the dependency list in each content file. If this flag is set for a dependency, only the resources are used and the actual content file is ignored.
### Importing & Backwards-Compatibility
Most of the current content exists in a form that is not compatible with the new system.
In most cases this can easily be resolved by adding an importer tool to the launcher, that takes the content and copies it into the desired organisation scheme (archive or directory).
For other content (pre-existing data directories and Morrowind, since Morrowind and its add-ons are installed into the same directory) we need to maintain a level of compatibility with the old approach, that can be switched on and off as needed.
During the discussion about the new content file organisation scheme (omwgame, omwaddon) there was some criticism about the scheme not allowing plug-ins with no dependencies.
This is not a problem, because such plug-ins are generally useless. A plug-in without any dependency can not modify or reference any record. That was not such a large issue with vanilla Morrowind, because in this case the plug-in could have still have depended on things like attributes or dynamic stats. However in OpenMW these will all turn into records and therefore can not be accessed from within an omwaddon file without dependencies. This will only get more extreme as the de-hardcoding progresses further. An omwaddon file without dependencies can do literally nothing, which makes it useless by definition.
But there is one exception. Some members of the mod community have provided resources packages (meshes and similar) that can be used by other content developers. Under our new resources scheme these would have to be accompanied by an omwaddon file. This is not a good solution because of two reasons:
* a omwgame file may need to depend on such a resource pack (currently impossible)
* a resource pack can be used by omwaddon files that depend on any omwgame file (also currently impossible)
Therefore we will introduce resources packs as a third kind of content type. Resources packs do not have dependencies and they can be placed in any position in the load order (provided the load order fulfils the dependency requirements of the content files depending on the resources pack). This will require some adjustments to the content file selector GUI.
Note that resources from a resources pack can still override resources from other resources packs and other content files earlier in the load order. Therefore the load order is highly relevant for resources packs too.
A resources pack consist of an omwres content file and the associated resources files. If we choose the file-name variant for identifying meta-data and the archive implementation path (vs sub-directory), we could theoretically skip the omwres content file and just make the resources archive the omwres file instead. However this is not a good idea, because that would leave us no way to carry along author and license information.
## Packaging
The editor will be enhanced with a packaging tool that can take a content file and its associated resources files and package them into a form suitable for distribution.
The question now is what is a suitable form. For Linux the first option that comes to mind are the respective software package management systems. This of course does not help Windows and Mac users. While there is the obvious and very reasonable answer ("Get a real operating system!") this seems unnecessarily harsh to Mac users and is overall not helpful.
Therefore we will develop our own cross-platform package format for OpenMW content. The exact scope still needs to be determined, but it could be as simple as an archive that holds the content file and the associated resources files. Giving this archive type a unique file extension (e.g. omwpack) would then allow the launcher to pick up opening requests (i.e. double click on the file) and install the content (optionally including a check for dependencies).
**Note**: Extensions to the scripting language in form of new instructions and functions are distributed over this entire document. In some cases, features may require additional functions that return the value of certain fields of certain records. These functions are usually not listed explicitly and are left as an exercise to the reader.
The version of the language used in a script is determined by a single integer number which is stored in a new subrecord within the script record. Note that this is different from earlier concepts, which used a more complicated version identifier and stored it within the actual script.
Scripts that are missing this subrecord are considered version 0 (legacy). New scripts (when created in OpenMW-CS) default to the most up-to-date version. The version can be selected from a combo box in the script subview. We may add a user setting that hides the combo box UI if the version is the most up to date one.
The version number is incremented whenever an addition to the scripting language is made (at most once per feature release). A new feature release is not required to increment the version number, if no feature changes have been made to the language in this release.
From version 1 on, all workarounds for bad scripts will be disabled. This should not break anything for well-written scripts. In general, moving to a new language version should usually at most require minor fixes.
Since old scripts will remain with the old language version (unless there is a need to modify them and use newer features), this scheme will not break compatibility for existing content.
We will continue with the existing runtime error handling scheme (i.e., stopping the script execution on a runtime error). Introducing exception handling instead would be overkill.
We will do our best to avoid crashes as a result of broken scripts. That means (among others) that we need to put an artificial (configurable) limit on function call depth to avoid crashes and lock-ups from endless script recursion. We may also decide to put a similar limit on loops.
We will flag `short` as deprecated. Currently `short` has no advantage over `long` (it uses the same amount of memory in OpenMW). For anything but a very specific kind of bit-cutting the `short` type has no use at all.
If we ever decide that we do want a shorter integer type we can always de-deprecate `short`.
Because we are discontinuing bad script workarounds, most ambiguity regarding string literals should have been removed already (we will not accept local variable names and instructions within quotation marks any more). Only a single problem case remains:
We cannot make a rule that forbids the use of local variable names that are also IDs, because that would allow random content files to break scripts in other, unrelated content files.
Therefore, the solution here is to simply give the local variable precedence over the ID. If the script author intended to give money to `Fargoth`, he should not have created a local variable with the same name.
Note that global variables are not an issue here, because global variables are IDs and IDs need to be unique (with certain exceptions that are not relevant here).
To remove even the last remaining potential problems with ambiguity, we will also introduce a new string literal that can only be a literal and never a string variable name. These literals are preceded by an `L` character. Utilising this feature, the aforementioned code block could be rewritten as is shown below, if the script author absolutely insists on having a local variable named `Fargoth`:
Since we currently have no way to reference an instance persistently, the use of the `Ref` type is limited for the time being (see section *Variable Scope* for further details).
References can be used in any place that would otherwise allow an ID that stand for an existing reference. The rules for strings regarding ambiguity apply to references in the same way.
*`Self`: A value of type `Ref` (the instance the script is currently running on, only available in local scripts and dialogue scripts)
*`NullRef`: A literal of type `Ref` (null reference)
*`GetId(r)`: Returns the ID of the reference `r` as a string value
* ``GetContainer(r)`: Returns the reference of the container `r` is in (or a null reference if `r` is not in a container)
*`GetCell(r)`: Returns the ID string of the cell `r` is in (either directly or via a container)
*`SearchActive(id, container = 0)`: Returns a reference with the given ID within the active cells. If `container != 0`, also check in containers; returns a null reference if no reference is found
*`SearchIn(id, id2)`: Returns a reference with the given ID within something (`id2`) that can contain references; this can be a cell, a worldspace, a container, a creature or an NPC. If `id2` represents an instance, a `Ref` variable can be given instead; returns a null reference if no reference is found
We will not support mixed-type lists because that would require a major change to the type system. Internally and functionally, a list will work like an array. The type names for lists are:
List literals are given as a comma-separated list of values in square brackets. Empty list literals are allowed. In the context of lists, we generally allow implicit promotion of integer to float types.
*`Set l1[i] To e`: Sets list element `i` of list `l1` to value `e` (indexing begins at 0)
*`Sort(l1, cf="")`: Sorts list elements into ascending order (if `cf` is an empty string) or via comparison function script `cf`
*`Filter(l1, ff)`: Filters list `l1` by filter function `ff` (only keeps elements that do not return 0)
*`Reverse(l1)`: Reverses order of list elements of list `l1`
*`Append(l1, e)`: Appends element `e` to list `l1`
*`Append(l1, l2)`: Appends elements of list `l2` to list `l1`
*`Remove(l1, e)`: Removes all elements equal to `e` from list `l1`
*`Remove(l1, l2)`: Removes all elements from list `l1` which are also in list `l2`
*`InsertAt(l1, e, i)`: Inserts element `e` into list `l1` at position `i` (moving the element at index `i` one position upwards and extending the size of the list by one)
*`RemoveAt(l1, i)`: Removes the element at position `i` from list `l1` (moving elements with an index higher than `i` down by one and reducing the size of the list by one)
*`Resize(l1, n)`: Set size of list `l1` to `n`; if the list is extended, additional elements are initialised with default values
In the specification of additional functions and instructions, values of these types are specified as `v3`, `v4`, and `v6` respectively. Passing shorter lists is allowed and will set the missing elements to 0.
All variable types will be available at all scopes with the exception of reference variables. Reference variables will be limited to true local scope (see below), because all other scopes require writing the variable to a saved game file and we currently don't have a general method to serialise instance references. This is a task for stage 2 or more likely OpenMW 2.0.
The global and the local scope remain unchanged. We will add two more scopes:
What the Morrowind scripting language describes as local variables does not match the concept of local variables in other languages. In case of local scripts, Morrowind local variables function as member variables. In case of global scripts, Morrowind local variables function as static variables.
* Prevention of potential scripting errors when the state of a local variable is maintained across multiple script executions and the script does not re-initialise the variable at the beginning of a new run
A common problem (especially relevant for large projects with complex functionality) is that there is no place other than global variables to store additional state that is not specific to an instance. A global function with multiple variables can be used instead, but that is just a workaround.
**Note**: Object record variables are essentially the same as old local variables declared in a local script - only that they are declared in an object record instead.
*`Has{Type}(vn)`: Returns 1 if record/reference has a long/float/string/list record variable of name `vn`, 0 otherwise
*`Get{Type}(vn)`: Returns the value of record/reference variable `vn`. Note that we don't use the x.y syntax here, because we need to explicitly specify the type to allow proper compile-time error checking for reference variables.
Within all functions and instructions, the record/reference is specified via the `->` operator in the usual way. When using object records (via ID), the first instance found is used instead of the object record.
We can fold the access of local variables in global scripts into the new record variable system, even though global scripts do not have explicit record variables. The new functions for record variable access make the old x.y syntax obsolete and, therefore, we declare it as deprecated.
We will add a `For` loop that works on lists. To avoid unnecessary complexity in the language and to encourage the use of lists, we will not have an index-based `For` loop (these can easily be simulated via `While`).
We may add a `switch-case` construct, but this is most likely a stage-2 task since there are many different ways to do `switch-case` and no obviously superior solution. This will most likely require extended discussion and design work.
We will add a function that moves an instance into the world. This feature (especially the `move` function) preludes a concept of persistent instance identity, which is most likely a stage-2 or OpenMW-2.0 feature. For now, these functions are required to deal with state attached to the instance in the form of record variables or old local variables respectively.
*`SetRotation(v3)`: Sets the instance's rotation; actors ignore the first two elements (replaces `SetAngle`)
*`SetPosition(v3)`: Sets the instance's position (replaces `SetPos`)
*`Teleport(target, v6, strict = 0)`: Teleports the instance to location specified by `target` and `v6`; actors ignore the first two elements; if `strict != 0`, no corrections are made to the specified location, otherwise the location may be adjusted for safety (replaces `Position` and `PositionCell`)
*`Spawn(objectId, target, v6, strict = 0)`: Same as `Teleport`, but spawns a new object `objectId` (replaces `PlaceItem` and `PlaceItemCell`)
We will add functions to modify and query other non-item-specific state that is already present in the cellref class and therefore already written to saved game files.
We introduce compile-time constants for object types (Weapons, Activators and so on). These have integer values. The constants must be named consistently in such a way that name collisions are unlikely (e.g. `TypeWeapon`, `TypeActivator`).
A query returns a list of instances within a certain area. Along with the description of the area, the query takes a list of object types (`t`) as an additional argument.
We will deprecate `MessageBox`. As a replacement, we will introduce new instructions for creating message boxes (see following subsection and *GUI* section) without a formatting feature and separate text formatting functions.
*`Str(v, p = -1)`: Returns a `String` containing the string representation of the numeric value `v`. `p` specifies the number of digits after the decimal point. If `p == -1`, a suitable value depending on the type of `v` will be chosen
*`LFormat(s, a)`: Returns a `String` equal to the `String``s` with all occurrences of %x replaced with the respective element indexed x from the string list `a`
*`Join(l, s)`: Returns a `String` consisting of the members of the `StringList``l` separated by the `String``s`
*`sl` is a list of strings, defining the available options
*`f` is the ID of a script function that is called when an option is selected; the function takes one `long` argument (the option index, starting at 0)
*`fl` is a list of script function names with the same length as `sl`; the functions do not take any arguments; empty strings in the list are allowed, which makes OpenMW ignore the respective choice
Argument lists are allowed to be empty and are comma-separated. Elements in argument lists are type-name pairs. Elements can be given default values in a C++ fashion.
Calling a function pauses the execution of the calling script, executes the called script and then resumes the execution of the calling script. This is different from the `StartScript` and `StopScript` instructions. The `StartScript` instruction is not modified (i.e., no argument passing).
A function call must be performed via a function name literal. The function name cannot be given as a string variable, since this would make it impossible to check for the correctness of the function signature at compile time.
We introduce two new record types (hook, hooked script). The hooked script is a generalisation of the concept of a start-up script. We may decide to fold the start-up script record type into the hook record type.
By building hook IDs in this way, we allow content files to delete hooked script records in dependencies without the need for an additional ID that identifies individual hook records.
**Note**: If more than one script is attached to a hook, the order in which the scripts are executed is, at this point, implementation-defined and, thus, scripts must not depend on a specific order.
A hook record declares a new hook. Each hook record contains a list of argument types with optional default values (again comparable to C++ function calling).
There will be no return values (problematic since there can be multiple scripts per hook).
We provide system hooks within the namespace `sys` that are called in specific situations (see the section about de-hardcoding for some examples). Content developers may also provide their own hooks (user hooks).
System hooks are not added to content files, since they cannot be modified by content developers anyway. We will instead inject the system hook records on content-file load.
We define the term script slot as an optional subrecord in an object record that contains the name of a script. The default script slot for most object types is the "Run-Once-Per-Frame" slot, a.k.a. local script.
The default slot does not take any function arguments, but other slots can. The function arguments of a script attached to a slot need to match the hardcoded argument list of the slot.
**Note**: If two scripts attached to the same object both define a (non-true) local variable with the same name, there will be only one variable. It is an error if the type of these variables don't match.
We may allow the addition of custom slots (defined by the content developer), though this is an advanced feature more likely to be implemented in stage 2. Further details need to be explored.
IDs in a script refer to the local namespace by default, meaning the ID `a` in the script `b::c` would refer to `b::a` if such an ID exists, or to `::a` otherwise.
*`GetPcTarget`: Returns the reference of the instance the player is currently looking at (crosshair); can be a null reference
*`GetMultiplayer`: Always returns 0
*`GetPlayers`: Returns a list of references to all player-controlled instances; this list contains a single reference to the instance of object `Player`
The distinction between interior and exterior cells stopped making sense with the release of the Tribunal add-on. Therefore, we should drop this terminology and replace it with **Unpaged Cells** (interior) and **Paged Cells** (exterior).
By default, each unpaged cell has an associated worldspace record with the same ID. Furthermore, the unpaged-cell record is enhanced by an optional subrecord that specifies an alternative worldspace (if present).
By moving out the worldspace into a separate record, we can unify worldspace data between interior and exterior cells. We can also associate multiple interior cells with the same worldspace or interior cells with an exterior worldspace. This should reduce duplicated data significantly.
Currently, there is no uniform ID scheme for cells. Interior cells are named via an ID, exterior cells are named via a cell index (x, y). This needs to be changed, since we need a more consistent way to address cells.
The editor already gives exterior cells an ID (currently in the form of `#x,y`). The new scheme (relevant at least for the editor and scripting) will be `worldspace::x,y` (the cell will have the ID `x,y` in the namespace `worldspace`). We may also consider to replace the two integer coordinates in the cell record with the string ID. The performance impact of this change should be insignificant.
The default exterior worldspace will be called `default` (previously called `sys::default`). Therefore, the old exterior cell 0, 0 will be called `default:0,0`. We are moving `default` out of `sys` to avoid creating an exception to the rule that content files are not allowed to create records in `sys`.
* Water: Default Water Level, Water ID (see de-hardcoding). **Note**: Script instructions that modify the water level will now modify the water level of a worldspace instead the one of a cell.
Vanilla references to cells are generally based on the ID of the cell. There are no fields in vanilla Morrowind's data structures that reference individual exterior cells.
The existing script instructions that deal with water level can be safely extended to the new system. We will add an optional argument at the end of the argument list of each instruction (`GetWaterLevel`, `ModWaterLevel`, and `SetWaterLevel`) which specifies the worldspace the instruction is acting on. If the argument is missing, the instruction affects the current worldspace instead.
* Inside script delta (float, optional): Minimum time between two executions of the inside-script function.
* Composite (integer, optional): If this flag is set, the area will be ignored by OpenMW except as a part of a joined area. **Note**: Composite areas are not accessible by script instructions and do not run any scripts of their own.
A joined area is an area that consists of multiple unjoined areas. Joined areas can contain both composite and non-composite areas. A joined area can stretch across multiple worldspaces. Scripts do not distinguish between areas and joined areas.
We will add an instruction to delete instances via a reference variable. Current solutions are insufficient because they can not target specific items (when in a container) and require different approaches depending on whether an instance is in a container or in the world. Self-deletion must be safe. For the sake of consistency, we extend this instruction to work on non-item objects too.
We will add a function that returns the contents of a container as a list of references. **Note**: In this case, the term "container" also includes creatures and NPCs.
We will add a function that moves/clones an item instance into a container (actual container or actor). This feature (especially the `move` function) preludes a concept of persistent instance identity, which is most likely a stage-2 or OpenMW-2.0 feature. For now, these functions are required to deal with state attached to the instance in the form of record variables / old local variables. (In all cases, the reference specification for the item to be moved/cloned works via the `->` operator in the usual way.)
Objects also have implicit item tags that are determined by their type (e.g., every weapon object has a tag "Weapon" even without the object record explicitly containing this tag). We may introduce other kinds of implicit tags (e.g. weapon types, enchanted items).
* The player presses the attack button while holding an interaction item in his hand and targeting an object in the world. This feature exists in vanilla Morrowind only within the Security skill. We generalise this kind of interaction (see *Held Items* in the *De-Hardcoding* section). We also allow this feature for weapons held in the main hand: If an interaction is possible, the interaction takes the place of the attack. If the interaction is ignored or refused, the attack proceeds.
* The player drags an item from a container onto an instance in the world. This kind of interaction does not exist in vanilla Morrowind.
* The player drags an item from a container onto another item in another (or the same) container. This kind of interaction does not exist in vanilla Morrowind.
If the action is accepted or refused, the chain stops. If the action is refused or the chain runs to its end without any script accepting it, the player will be notified via a sound effect. We may either re-purpose an existing sound effect or acquire a new one.
Using any of these instructions outside of an interaction chain is an error. We use these instructions instead of return values, because a part of the interaction chain works via hooks which do not provide return values.
This section describes the first batch of de-hardcoding tasks. This is the core part of stage 1 (*The Grand De-Hardcoding*). We are aiming mostly for low-hanging, but highly profitable fruits here. More complex de-hardcoding (especially tasks that require more extensive script support) will follow in stage 2.
Many GMSTs will be integrated into other records, which will effectively remove the GMST. We may consider actually removing the GMST record during the load process.
We may consider allowing content files to create new GMSTs outside of the `sys` namespace. This would make the GMST record type more consistent with other record types. To make this addition useful, we need to add script functions to read GMSTs:
The *openmw.cfg* file contains a set of fallback values. These were extracted from the *Morrowind.ini* file. As the name indicates, we consider these values as a fallback for legacy-format content files only. Our goal is to move all these values to content file format. In some cases, we may also decide to declare a fallback value obsolete and not use it at all.
*`Enumerate{x}`: Returns a `StringList` of the IDs of all records of the respective type; `{x}` is either "Skills", "Races", "Classes", "DynamicStats", "Attributes", "WeaponTypes", "ArmorTypes", "Specialisations", "MagicSchools", "Factions" or "Birthsigns"
We will unify dynamic stats and make them configurable. For stage 1, we will not allow the deletion of existing dynamic stats (they are used in too many parts of the engine). But we will allow new dynamic stats.
We add a new record type for dynamic stats. Records for Health (`sys::Health`), Fatigue (`sys::Fatigue`), and Magicka (`sys::Magicka`) will be created by the engine when loading older omwgame files (these records are mandatory for newer omwgame files).
* (optional) PrevID: ID of the stat the engine will try to subsequently sort this stat in (similar to info records)
* (optional) NextID: ID of the stat the engine will try to antecedently sort this stat in (similar to info records)
* (optional) Vital: Flag which specifies whether the player dies if the stat drops to 0
* (optional) Level-Up Function: ID of the stat's level-up function, which takes the reference of the character as argument and returns an `long` value representing the maximum stat change achievable with a level-up
* (optional) Time-Passed Function: ID of the stat's time-passed functionm, which takes the reference of the character and the duration as arguments and returns a `float` that is used to modify the current stat value (the function is not used when waiting or sleeping)
* (optional) Wait Function: ID of the stat's wait function, which takes the reference of the character, the duration, and a sleep flag (integer) as arguments and returns a `float` that is used to modify the current stat value
* Default Value: Value that is used as the maximum value of the stat if an actor does not have this stat (possible if the stat was defined in an add-on and not in the base game)
Scripts for default stats are injected as necessary. Some of these scripts require access to GMST values. We need to figure out how to implement this: either grab the value from the GMST when adding the script or adding a script function to read GMST values. The latter is easier but will not allow us to remove the redundant GMST records easily.
The currently existing `Get`, `Set`, and `Mod` instructions are flagged as deprecated and replaced by a single instruction for each operation that takes the stat ID as an argument. We need separate instructions to deal with base, modified and current values.
We will unify attributes and make them configurable. For stage 1 we will not allow the deletion of existing attributes (they are used in too many parts of the engine). But we will allow new attributes.
We add a new record type for attributes. Records for the existing attributes (`sys::NameOfAttribute`) will be created by the engine when loading older omwgame files (these records are mandatory for newer omwgame files).
* Tooltip Text (taken from GMSTs for default attributes)
* (optional) PrevID: ID of the attribute the engine will try to subsequently sort this attribute in (similar to info records)
* (optional) NextID: ID of the attribute the engine will try to antecedently sort this attribute in (similar to info records)
* Default Value: Value that is used as the maximum value of the attribute if an actor does not have this attribute (possible if the attribute was defined in an add-on and not in the base game)
The currently existing `Get`, `Set`, and `Mod` instructions are flagged as deprecated and replaced by a single instruction for each operation that takes the attribute ID as an argument. We need separate instructions to deal with base, modified and current values.
Additionally, we will add a new GMST `sys::ClassAttributes` of type `long`. This GMST specifies the number of favoured attributes that a class has. The value defaults to 2.
We add a new record type for weapon types. Records for the existing weapon types (`sys::NameOfType`) will be created by the engine when loading older omwgame files.
* Handling Type: Defines how the weapon is held and what animations play when attacking
* Hit Test Script: Name of the hit test script used (see *Combat* subsection)
For stage 1, the weapon type record is still very basic. Its purpose is mostly to allow better de-hardcoding of skills. We may expand on this in the future. However, there are already possible uses, e.g., a weapon type "Ancient Blades" which requires a separate skill.
In vanilla Morrowind, armour types exist only implicitly. There is no record and no option to select armour types. Armour types are determined by weight only.
Records for the existing types (`sys::LightArmorType`, `sys::MediumArmorType`, `sys::HeavyArmorType`) will be created by the engine when loading older omwgame files (these records are mandatory for newer omwgame files).
For stage 1, the armour type record is still very basic. Its purpose is mostly to allow better de-hardcoding of skills. We may expand on this in the future. However, there are already possible uses, e.g., imitating TES IV: Oblivion by eliminating medium armour or adding a new armour type such as "Ancient Armour" which requires a separate skill.
We add a new record type for specialisations. Records for Combat (`sys::CombatSpec`), Stealth (`sys::StealthSpec`), and Magic (`sys::MagicSpec`) will be created by the engine when loading older omwgame files.
We add a new record type for magic schools. Records for the existing magic schools (`sys::AlterationMagicSchool`, `sys::ConjurationMagicSchool`, etc.) will be created by the engine when loading older omwgame files.
A use for the specialisation field would be, e.g., dividing magic into the two categories "Divine Magic" and "Arcane Magic" and having characters specialise accordingly.
Skills are a complex topic and we won't achieve full de-hardcoding in stage 1 - and most likely there will never be a 100% complete de-hardcoding. But there is still a lot we can do with skills.
Currently, skills exist as indexed records. We need to move these over to ID-based records. The exiting indices are translated to IDs of the form `sys::NameOfSkill`.
The currently existing `Get`, `Set`, and `Mod` instructions are flagged as deprecated and replaced by a single instruction for each operation that takes the skill ID as an argument. We need separate instructions to deal with base and modified values.
*`UseSkill id, v`: Progresses the skill `id` by a value of `v` (`float`).
*`UseValueSkill Id, i`: Progresses the skill `id` by the value given by the use-value field with index `i` (0, 1, 2 or 3)
*`Get{x}SkillLevel s_id`: Returns the skill level of a function subrecord with `TargetId``s_id` (`String`). `{x}` is either "Armor", "Weapon", or "Magic"; see the next subsection for details.
**Note**: We do not de-hardcode the fixed number of use-value fields. The usefulness of these fields for new skills is most likely limited. The `UseSkill` instruction, which bypasses the use-value fields, should be sufficient in most cases. We only add the `UseValueSkill` instructions to better support script interactions with default skills.
A function subrecord describes how a skill interacts with hardcoded engine functions. A function record consists of a function ID (we use an index here, because the list of functions will definitely not be extensible by content files) and additional arguments.
We do not forbid non-unique function subrecords, i.e., two skills may have identical function subrecords, e.g., two skills governing light armour. If there is more than one skill with the same function subrecord and the skill level for this function needs to be considered, we use the maximum of all relevant skill levels.
We make armour skills fully customisable by introducing a function ID for armour types. Any skill that has a function subrecord with this ID is an armour skill. For default armour skills loaded from older omwgame files, we will inject function subrecords during the loading process.
The `TargetId` of an armour function subrecord indicates the armour type that the skill is governing.
We make weapon skills fully customisable by introducing a function ID for weapon types. Any skill that has a function subrecord with this ID is a weapon skill. For default weapon skills loaded from older omwgame files, we will inject function subrecords during the loading process.
The `TargetId` of a weapon function subrecord indicates the weapon type that the skill is governing.
We make magic skills fully customisable by introducing a function ID for magic schools. Any skill that has a function subrecord with this ID is a magic skill. For default magic skills loaded from older omwgame files, we will inject function subrecords during the loading process.
We make weather types customisable by moving from hardcoded, index-based weather effects to ID-based weather types stored in content files. To achieve this, we introduce a new record type ("Weather"). When loading older omwgame files, we will inject weather records for the ten default weather types (`sys::WeatherAsh`, `sys::WeatherBlight`, etc.).
Magic effect subrecords contain the ID of the respective magic effect. All other subrecords contain an integer ID specifying the effect and (if necessary) additional parameters.
* "0": Scripted event; additional data consists of the name of the script to be run when the event is triggered; the script takes the following arguments: worldspace (`String`), location (`Vector3`), weather ID (`String`)
* Chance: Floating number in the range between 0 and 1; the chance per unit of time that the event happens (we may want to make the unit of time globally configurable with a new GMST)
* (optional) Min-Distance: The minimum distance from the player at which the effect can take place (0 by default)
* (optional) Max-Distance: The maximum distance from the player at which the effect can take place (infinite by default)
We need to introduce new script instructions regarding the weather, since the existing instructions are based on a fixed number of weather types or integer-indexed weather types. These instructions can not be salvaged and we therefore declare them deprecated.
*`SetWeather(regionId, weatherId)`: Sets the current weather for the region with the ID `regionId` to `weatherId` (replaces `ChangeWeather`)
*`GetWeather(regionId)`: Returns the current weather ID for the region with the ID `regionId` (replaces `GetCurrentWeather`)
*`SetRegionWeather(regionId, weatherId, chance)`: Modifies the entry `weatherId` in the weather table of the region with the ID `regionId`; `chance` is of type `long`; we relax the requirement that the sum of the chance values needs to be 100 (replaces `ModRegion`)
*`UpdateRegionWeather(regionId)`: Forces a new roll on the weather table of the region with the ID `regionId`
We currently have but a single water type that is hardcoded. We name this water type `sys::Water` and inject a suitable record of the new type (see below) during loading of older omwgame files.
We generalise the concept of water to the concept of liquid by introducing a new record type ("Liquid"). Liquid records can be used both for different-looking water types (e.g., more swampy water, water with different colouration) but also for completely different liquid types (e.g. lava).
**Note**: Morrowind only uses one liquid type, which we refer to as "water". (While lava does exist in the game, it is handled with activators, rather than as a liquid type)
To support the water type `sys::Water`, we also need to add a new magic effect (`sys::SuffocationEffect`).
Liquid records are referenced both in worldspace records (see *Cells, Worldspaces & Areas* section) and in the body of liquid records (see *Misc* section).
We also introduce a new effect (`sys::SuffocationEffect`) by injecting a record when loading from older omwgame files. This effect triggers the normal procedure for running out of air.
* (optional) Effect Function: Contains the ID of a script function that is called when the magic effect takes effect; the function takes two arguments: the reference of the effects source (this would be a spellcaster in case of a spell or an item in case of an enchantment) and a list of target references
* (optional) Wear-Off Function: Contains the ID of a script function that is called when the magic effect ends (only relevant for non-instant effects); the function takes the same two arguments as the "Effect Function" field
For the existing effects, we will inject scripts that match the previously hardcoded effects when loading from an older omwgame file. This will require the addition of a significant number of new script instructions that are all trivial, since they will just call existing engine functions.
It is important to generalise as much as possible when creating these new script functions, e.g., we won't have a `DivineIntervention` script instruction. Instead we add a `GetClosestMarker` function, use existing functions for querying position and cell and, then, use the new `Teleport` instruction.
We allow the addition of customisable input functions that can be bound to keyboard buttons in the usual way and can trigger the execution of scripts. Existing input bindings are not affected by this.
We merge the probe and lockpick object types into a new object type: "Held Item". The Security-skill-related functions are handled via the `ItemObjectInteraction` script subrecord. When loading older omwgame files, a suitable script in the `sys` namespace is injected for probing and lock picking each. When transforming probe and lockpick records into held-item records, an `ItemObjectInteraction` subrecord referencing the respective script is injected.
**Note**: If we enhance the animation system, we may need to add additional subrecords that specify the pose for holding the item or the animation for using it.
We add a new GMST (`sys::ReversePickpocketing`) of type `long` that indicates if reverse pickpocketing is allowed (value other than 0) or not (value 0).
We move the function for checking if pickpocketing succeeded from the C++ code to a new script function (`sys::PickpocketTest`). We inject this function when loading older omwgame files.
De-hardcoding combat is a monumental task that we can not hope to complete within the time frame of stage 1. We will de-hardcode some parts that do not depend on large-scale improvements to animation and can be handled with the scripting improvements in stage 1. Any further enhancements are left for stage 2 or, more likely, OpenMW 2.0.
*`<NameOfMeleeHitTest>(weaponId, targetId)`: Function for melee weapons defined in the corresponding WeaponType record; `weaponId` refers to the weapon used, `targetId` refers to the ID of the target
*`<NameOfRangedHitTest>(weaponId, targetId, ammunitionId)`: Function for ramged weapons defined in the corresponding WeaponType record; `weaponId` refers to the weapon used and `targetId` refers to the ID of the target, and `ammunitionId` refers to the ammunition used by the ranged weapon
*`sys::UnarmedHitTest(weaponId, targetId)`: Default function for unarmed attacks; `weaponId` refers to the weapon used and `targetId` refers to the ID of the target
`sys::UnarmedHitTest` and default functions for armed-hit tests (`sys::MeleeHitTest` and `sys::RangedHitTest`) are injected when loading older omwgame files.
*`GetTargetRef`: Returns the current target of an actor; returns a null reference if the actor is not in combat or if it is used on an instance that is not an actor
*`DeclareWar l`: Similar to `StartCombat`, but specifies a whole group of enemies; `l` is a list of references
*`DeclarePeace l`: Ends the hostilities resulting from previous combat towards the actors listed in the reference list `l`. **Note**: We may need to add a grace period after this instruction during which attacks do not cause hostility again, so we can handle non-instant attacks.
*`sys::Kill`: Executed whenever an actor is killed; scripts for this hook take the following two arguments: reference to the target and reference to the actor who killed the target (may be a null reference)
*`sys::CombatStarted`: Executed when the player enters combat
*`sys::CombatEnded`: Executed when the player exits combat
Background music is music that (potentially) runs all the time, unless explicitly stopped. Background music is always looping.
Event music is played only on certain events. Event music can be played looped or only a single time. In the former case event music needs to be stopped explicitly. Once event music ends background music is resumed exactly where it was interrupted.
Background and event music persists through save-load-cycles.
### Script Enhancements
We add several new script instructions:
* PlayBackgroundMusic (t)
* PlaylistBackgroundMusic (pl)
* StopBackgroundMusic
* PlayEventMusic (t, loop=0, force=0)
* PlaylistEventMusic (pl, loop=0, force=0)
* StopEventMusic
Arguments:
* t (string): a single title (specified by its location in the data directory)
* pl (string): a playlist (specified by its ID)
* loop (integer): looping or not
* force (integer): Terminate any other running event music first. If this flag is 0 and there is already event music playing the new event music is ignored. Event music provided by content developers will usually not set this flag.
Note: An attempt to play a track or playlist that is currently playing is ignored. In this case the track or playlist does not restart.
### Transition of Existing System
We completely replace the old music system with a new script-based one. The StreamMusic script instruction is flagged as deprecated.
New records are injected when loading from an older omwgame file.
We add two playlists (sys::ExplorePlaylist and sys::CombatPlaylist) which are pointed to the usual directories and play with a probability of 1.0.
We add a GMST (sys::DefaultBackgroundMusic) with a default value of "sys::ExplorePlaylist". Whenever starting a new game or loading a game with no background music running the playlist specified in this GMST is played as background music. If the GMST holds an empty string no background music is played by default.
We add a script to the sys::CombatStarted and sys::CombatEnded hook each. The former plays sys::CombatPlaylist looped and forced. The latter stops event music.
We add an optional string sub-record to the records listed below. This field contains a single track or a playlist that determine the background music for the respective location.
More specific entries (towards the bottom of the list) take precedence over more general entries. Global background music (controlled via script instructions) has the lowest priority.
## Character Creation
The process of character creation currently allows for very little customisation. We redo the character creation process with the following goals in mind:
* Allow more control over how the individual steps are chained together
* Allow additional steps (both future hardcoded enhancements like additional visual customisation and custom steps entirely defined in content files)
* Allow replacement of existing steps with alternative methods
Currently the character creation process runs through these steps:
3. Choose a method for class selection and perform class selection (3 methods)
4. Choose birthsign
5. Review
### Chaining
We add two new GMSTs to control how the steps of character creation are chained together:
* sys::NewCharBack: Integer; allow going back to previous steps (not being able to go back also implies that there is no going forward)
* sys::NewCharSteps: String-List: List of scripts associated with the steps of the character creation process. The scripts are listed ordered according to the sequence they are executed in.
Each character creation step has a an associated script that is called when the step is reached (either via a EnableX script instruction or via the player going back or forth).
### Script Instructions
We add several new script instructions.
* CharacterCreationRun (n): Opens the respective GUI/window
* SetPlayerName (name)
* SetPlayerRace (id)
* SetPlayerFace (id)
* SetPlayerHair (id)
* SetPlayerSex (i): 0 or 1
* SetPlayerClass (id)
* SetPlayerBirthsign (id)
* CharacterCreationBack: Go back to previous step
* CharacterCreationNext: Go to next step (ignored if the next step had not been accessed before)
* 2: Class selection via picking an existing class
* 3: Class selection via creating a class
* 4: Birthsign GUI
* 5: Review GUI
### Transition of Existing System
When loading older omwgame files we inject two GMSTs (sys::NewCharBack and sys::NewCharSteps) as well as several scripts.
For each step we add a new script that consists of only a single line:
````
CharacterCreationRun n
````
where n is the appropriate index.
Only steps #3 will be handled differently than described above.
The class selection method GUI can be implemented entirely with a message box. Therefore we scrap the hard-coded method selection window entirely.
Likewise the character selection method of answering a set of quests can be implemented via a set of message boxes. Therefore we scrap this window too.
## Level-Up
The vanilla (character-)level-up system allows almost no modification. We keep the existing hard-coded system, but make it more configurable, and we also allow content developers to completely replace the existing system.
Checks for a level up are based on the skill progression since the last level up. In vanilla this state is not accessible to content developers or players.
We address this issue by turning these hidden variables into record variables attached to the player character. The variables have the type long and a name matching the ID of the skill, and are created on the fly whenever the engine detects a skill level up. Note that regular script instructions that change skill level do not count towards level ups.
We also add another record variable (LevelUpCount) that counts the number of major and minor skill level-ups.
By binding these stats to a character instance instead of using global stats we are also making preparations for optional future level up mechanics for NPCs (companions or otherwise). This is most likely a task for stage 2 though.
### Trainers
Some NPCs are flagged as skill trainers. These trainers can train the player in their three best skills. Skill levels gained via training count towards level-up. We make the following enhancements to this mechanism:
* New GMST (sys::SkillTrainCount, integer): Replaces the hard-coded value of 3 skills.
* New script (sys::SkillTrainingTest): Tests if NPC can train player in a skill (returns 0 or 1). This test is performed after the faction standing test and after the skill list is trimmed down via sys::SkillTrainCount. The function takes the following arguments: ref to player, ref to NPC, ID of skill
* New script (sys::SkillTrainingApplied): Executed after training has been completed. Arguments are the same as with sys::SkillTrainingTest.
When loading from an old omwgame file, GMST and scripts are injected. sys::SkillTrainCount defaults to 3, sys::SkillTrainingTest performs the usual tests on skill level and attributes and sys::SkillTrainingApplied defaults to an empty script.
The level-up test is performed when either the player rests (by default via T key) or when the ShowRestMenu function is called.
The test is performed by calling the function sys::LevelUpTest, which returns either 0 or 1. If 0 is returned no further action is taken. If a value other than 0 is returned the usual level-up procedure continues. Note that this function is allowed to initiate a custom level-up procedure and return 0.
The function takes two arguments:
* A ref to the player
* An integer that indicates what started the level-up test (-1 for resting)
We enhance the ShowRestMenu instruction with an optional long argument (defaults to 0) that is passed to the sys::LevelUpTest function as second argument.
When loading from an older omwgame file we inject a sys::LevelUpTest script that matches the hardcoded version of the level-up test.
### Level-Up Procedure
We keep the level-up procedure but replace several hardcoded values with GMSTs.
* Number of major skills: sys::MajorSkillCount (default: 5)
* Number of minor skills: sys::MinorSkillCount (default: 5)
* Number of attributes to increase during level-up: sys::AttributeLevelUp (default: 3)
We add a new function (sys::AttributeIncrease) that determines the number of points an attribute can be increased. The function takes a reference to the player and the ID of the attribute as argument and returns the number of attribute points. As usual we inject a matching function that matches the hardcoded implementation.
We add localisation records (see section about localisation) of the form default::LevelUpMessageX, where X is a positive integer number. When loading older omwgame files these records are injected based on level up fallback values. We use the default namespace instead of sys, because content developers need to be able to add their own records.
We add a script (sys::LevelUpFinished) that is called after the level-up procedure has been completed. The script takes a reference to the player character as its only argument.
The default implementation (injected when loading from an older omwgame file) resets the skill record variables and reduces the LevelUpCount variable by 10.
The level up dialogue contains an image that depends on how the skill increase is distributed among specialisations. The function that decides about this image is very simple. However, since specialisations won't be hardcoded any more, we can not simply pass these values into the function without first establishing more involved script support than planned for stage 1.
This is actually not a problem since we can simply track the increase values in record variables, which may also prove useful for other purposes.
With this modification the C++ function (MWGui::LevelupDialog::getLevelupClassImage) can be directly translated into a script function (sys::LevelUpImage).
Note that this change does not allow for easy addition of new classes to the scheme. This is not a feature present in vanilla MW either. We may decide to investigate other options than simply translating the C++ function into a script function.
## Trading
### Pricing
The algorithm for trading (implemented in MWMechnics::Trading::haggle) can be translated straightforward into a script function once all stage 1 script enhancements are in place.
### Restocking Money
Currently the frequency of money restocking is controlled by a the GMST fBarterGoldResetDelay. Money is always reset to the original value.
We make all of these aspects configurable by adding a new field to all actor record types (NPC, creature) that contains a script ID.
The script takes a reference to the actor as its single argument.
When loading older omwgame files we inject a script (sys::UpdateGold) and inject this ID into all actor records that are flagged for merchant services. We also add a record variable (last restock).
The script checks the current time against the last restock variable and the GMST and resets the gold if necessary.
### Restocking Items
Currently items are restocked after every trade. Items in the merchant's inventory and in all containers owned by the merchant are restocked to their original count.
This process is complicated by the existence of levelled item lists, which makes it too complex to re-implement in a script.
We will make several changes to increase the flexibility of item restocking.
1. Check if a refill should be performed; called at the beginning of every trade cycle. Arguments: ref to actor, integer (1 if first trade since talking to the merchant, 0 otherwise). Returns an integer (0 no refill required, otherwise refill is required). If this script is not present, a refill is performed).
2. Called for every item that the refill algorithm flags for removal. Arguments: ref to actor, ref to item. Returns an integer (0 if item should be kept, otherwise item is removed). If this script is not present, the removal takes place.
3. Called at the end of refill procedure. This gives content authors the opportunity to make other modifications. Arguments: ref to actor. No return value.
Morrowind offers a wide selection of fast travel options. Each of these fall into one of three categories:
1. Spells and teleport items
2. Travel to fixed locations via paying a travel NPC (boat, slit strider, gondola, guild guide)
3. The propylon chamber system
With vanilla Morrowind and other stage 1 changes #1 and #3 are already sufficiently configurable. #2 is not.
In stage 1 we will improve the flexibility of the travel network system and also its usability both for content creators and for players.
### Travel Network Record
We introduce a new record type (Travel Network) that consists of the following fields:
* Colour (integer)
* ID of Cost-Script (string): Takes three arguments (ref to travelling character, ID of source location record, ID of destination location record) and returns a long (number of coins). This is the value before bartering and followers are taken into consideration.
* ID of TravelTime-Script (string): Takes three arguments (ref to travelling character, ID of source location record, ID of destination location record) and returns a float (duration in hours)
* ID of TravelCompleted-Script (string, optional): Takes three arguments (ref to travelling character, ID of source location record, ID of destination location record). Executed when a character has finished travelling.
* Auto-Knowledge (integer, flag): Is the travel network fully known from the beginning of the game (!=0) or do locations need to be discovered to be usable (0).
* Visible (integer, flag): Is the travel network visible on the map?
### Travel Location Record
We introduce a new record type (Travel Location) that consists of the following fields:
* Travel Network ID
* Location worldspace (String)
* Location position and orientation (Vector4)
* Parent worldspace (String, optional)
* Parent position (Vector3, optional)
* List of IDs for travel locations that can be reached from this travel location
By formalising travel locations in this way we make it easier to modify travel locations later on (currently a modder would have to go through all travel NPCs of the same network, if he wanted to move a travel location) and to build visualisation features (see below).
### Travel Sub-records in NPC records
We keep the existing sub-record structures for travel since there is no automated way of transiting them to the new scheme. This task will be left to mod developers.
NPCs supporting the new scheme will have a single field that specifies the ID of the associated travel location record.
### Transition of Existing System
When loading older omwgame files we inject suitable travel network records. Unfortunately there is no procedural method to distinguish between boat, slit strider and gondola, so these will all have to be grouped together into an sys::TravelOthers network. It will be up to mod developers to untangle these.
The travel network records will be created with the visible flag set to 0, because old-style travel data isn't available at load time and therefore visualisation can not work.
Travel locations can not be automatically transitioned to the new system. This task is left to mod developers.
### Block List
The layout of a travel network is determined by the data in the content files and can not be changed during the game. However we do offer several methods to configure a network during the game.
* Location Block List: Individual locations can be dynamically blocked, either for incoming or outgoing connections or both.
* Connection Block List: Connections between two locations can be blocked dynamically. This blocking is directed, meaning blocking the connection from A to B does not automatically block the connection from B to A.
### Visualisation
We offer visualisation somewhat similar to [this](http://en.uesp.net/wiki/Morrowind:Transport).
Each travel network has a colour associated with it that will be used to mark connections. If a travel location has a parent section, the parent section will be used instead to determine the location (e.g. exterior location for guild guides inside a building).
Only networks flagged as visible are drawn. We may add a GUI element that allows showing/hiding of visible networks either as a group or individually.
* GetTravelLocationList (id, ignore_blocked=0): Returns a list containing the IDs of all locations of the travel network id
* GetTravelDestinationList (id, ignore_blocked=0): Return list of IDs of destination travel locations for the travel location id
We also introduce several new script instructions:
* SetTravelVisibility (id, visibility): Sets the visibility (flag) of a travel network (id)
* RevealTravelLocation (id): Flag a travel location as known
* BlockTravelConnection (source-id, destination-id, blocked): Block or unblock a connection between two locations
* BlockTravelLocation (id, incoming-blocked, outgoing-blocked): Block a travel location.
# NPCs & AI
## Navmeshes
The current system of waypoints is limited. It is unlikely that we can improve it much. This makes pathfinding one of the few cases were we seriously need to consider completely abandoning an existing system in favour of a new one (navmeshes in this case).
## Waypoints
Waypoints can still be useful, but in a different way. Content developers will often designate a specific location for a NPC to stand at or walk to. Currently the easiest method to achieve this is to place an instance at the location, note down the coordinates and then enter them into a script or a field in a record. This is not an efficient approach and also causes maintainability issues, when a location that is used in multiple parts of a content file needs to be moved.
We introduce a new record type (Waypoint) with the following fields:
* Position (Vector3)
* Worldspace/Cell Id (String; cell takes precedence over worldspace)
We also add a new script function:
* GetWaypointPosition (id): Returns a Vector3
Waypoints are not part of the cell data structures because they need to be accessed independently of cells and we don't want to search through (potentially) every single cell every time a waypoint is referenced.
## NPC Schedules
NPC schedules are an advanced topic and as such would be a better fit for stage 2. However schedules are also a very iconic feature with a large impact on the playing experience. Therefore we will consider them for stage 1. The following is a preliminary proposal that is in need of more design work.
### Active and Passive Cells
We run schedules only in active cells. But we also need to consider passive cells.
Here are a few examples. For simplicity let's consider a one-dimensional cell grid with the usual pattern of one cell around of the player cell being active.
For this example let the player be in cell 0. Now consider NPC A, who is in cell 2 (not active). He has a schedule that takes him to cell 1 sometimes. As a player we would expect to see him from the distance then.
Another example with the same setup as above: While A is moving within cell 2 towards cell 1, the player relocates to cell 2. He would to see A make his way towards cell 1. Moreover if the player moves back to cell 0 and then returns to cell 2, he would expect to see A having made some progress.
It is not clear yet how to achieve this goal best. In the most simple implementation we could just estimate the time it takes to perform a task in a schedule and spawn the actor into active cells accordingly. This would however not cover the second example.
Alternatively we could invent a semi-active cell state and apply it to all cells that contain NPCs whose schedules can touch the active cells. This semi-active state would not run any scripts, nor would it render or run animations, and it may use a simplified/limited form of physics. This approach would cover all cases. However, it has the potential for a severe performance impact.
Independently from the chosen implementation, we need to track all actors whose schedules are relevant to the active cells. This is a problem because with the default data structures we would at least need to scan every single cell on start-up for relevant actors. The performance impact of such an approach is most likely not acceptable.
Therefore information about which actor's schedule is relevant to which cell needs to be stored in a separate data structure that exists outside of the cell records.
### Schedule Record
We add a new record type (Schedule). A schedule consists of a list of task sub-records.
Each task sub-record consists of:
* A time of the day range
* An AI package
* Ignore flag (see next section)
The time table of a schedule is allowed to have holes (e.g schedule 1 ending at 10:00 and schedule 2 beginning at 10:15).
When picking a task from the schedule, all tasks which contain the current time are considered. Of these the task with the earliest start time is chosen.
When explicitly switching from one schedule to another, tasks with the ignore flag are ignored. This feature is intended for transitory tasks, that are pointless if the previous task hasn't been performed.
We add script instructions that allow for querying the current schedule of an actor. We also add a script instruction to prematurely end a task.
## AI Packages
To accommodate the NPC schedule feature and other enhancements to the AI system properly we need to redo the AI package system. We will deprecate the old packages.
This is an early draft of the new system and will almost certainly require more design work before we can cut it up into individual tasks.
### Idle
Idle activities are currently bound to the Wander package. This is suboptimal, both because other packages could benefit from it and because storing the idle function in a package instead of the NPC makes it hard to give the NPC a characteristic idle pattern.
We add a list of idle chances for each available idle animation to the NPC record. Ideally this list should be extensible, but first we need to improve the animation system so that the number of idle animations isn't hard-coded any more. This may be a stage 2 task.
The old wander package keeps its old idle list. When active it disables the new idle system.
If a NPC does not have any active packages the idle function is still active. In this case Chance and Dialogue Chance are determined by two new GMSTs, which default to 0 when loading older omwgame files.
* Legacy: Old packages, generated either via script instructions or via AI package list in the actor record. Removed once they run out (if not flagged for repeat). Deprecated.
* Schedule: Inserted by the schedule system. Can not be directly manipulated via script instructions.
* Manual: New packages, generated via new script instructions.
* Situation: Inserted via other game mechanics (e.g. combat, breath). Can not be directly manipulated via script instructions.
Packages of a type lower in the list take precedence over packages higher in the list. For the roles schedule and situation there can be only one package per actor at a time.
We add new script instructions to query the package state of an actor and to insert and remove manual packages.
### Duration
Each package has two fields that describe its duration:
* Repeat flag: Package adds itself again at the end of the end of the duration
Packages lacking these fields persist indefinitely unless explicitly removed.
Some legacy packages already have these fields. Schedule packages will not have these fields since the removal is controlled entirely by the schedule system.
### Updates Packages
We translate the packages AiFollow, AiActivate and AiTravel into the new format.
AiFollow and AiTravel specify a location by being given a set of coordinates and an optional cell ID. We will replace part of the package with a different format.
There are two possible locations sub-records of which each package may only contain one:
* A set of coordinates and a worldspace/cell ID (not optional)
* The ID of a (new type) waypoint (no worldspace ID required, since the waypoint includes that)
The other old-style packages require more extensive modifications.
### AiEscort
We can largely keep AiEscort with the following modifications:
* We use the new format to describe the target location (see above)
* Instead of a single location the package lists a sequence of locations, which will allow content developers to make actors escort the player along certain paths and around dangerous areas without resorting to multiple AI packages.
### AiWander
Instead of a location and distance based AI wander, we add a new package that limits the wandering to a single area.
There shouldn't be much need for this package, since AiPatrol and AiVisit offer better alternatives. But we offer it anyway to cover cases where neither of the new packages is seen as useful.
### AiPatrol
This is a new package with no direct equivalent in the old system. The package contains the following fields:
The actor will walk from one location to the next. Once he has reached the last location he will either continue with the first location (if the loop flag is set) or walk down the list of locations in opposite direction and then start over (if the loop flag is not set).
The obvious use case for this package is a guard patrolling a perimeter or a place.
### AiVisit
This is a new package with no direct equivalent in the old system. The package contains a list where each list item contains the following fields:
* Location
* Duration (float)
* Chance (float)
An actor with this package will randomly choose a location from the list according to the chance field (locations with higher chance are picked more often), then move to this location and stay there until the duration has expired and then continue from the top.
This package is intended as an alternative to the old AiWander. Hopefully (by giving the NPCs actual places to go to instead of just wandering around aimlessly) it can achieve NPC behaviour that is less silly looking and at least gives the appearance of making sense.
# Localisation
## Problems
There are two fundamental problems with the way localisation is handled in vanilla MW:
* Localised strings are used as internal identifiers that are referenced by other parts of the content
* Localised strings are intermixed with other records
This results in multiple issues:
* When localising the developer must hunt down all references to the localised strings and change them manually (cell names and topics).
* When updating a localisation to a new version of the content file the translator has to manually pierce together his old translation and the new content file.
* Changing a string that is used as an internal reference breaks the connection to the referenced records in relation to the non-localised file, which in turn makes it impossible to utilise automated tools that help for the localisation process.
* Content files of mismatching languages generally can't be combined in a content file list. Mixing languages is generally not desirable for playing, but may sometimes be unavoidable. The ability to mix languages is highly desirable for developers (e.g. debugging).
## Encoding
We already use UTF-8 internally. For post-1.0 versions of content file formats we will also use UTF-8 exclusively.
## Localisation Content Files
Localisation will be contained in separate content files (omwlang) that are to be loaded on top of the content file to be localised.
The launcher will treat a content file and its localisation file as a single entity (see section about Identifying Meta-Data).
We may add a launcher language setting that determines the default language chosen by the launcher. This needs to be a separate option from the legacy encoding setting, which is currently also called language setting.
A common localisation scheme is to use the English text as a key. This way non-localised text does not need to bother with the localisation mechanism at all.
This is not a good idea, both in general and particularly in our case:
* The assumption that English is the base language fails in certain areas of the MW community.
* Text does not always translate 1-to-1 between languages. A popular example is the term Free Software. The free has two meanings: free as in free speech and free as in free beer. But in other languages (e.g. German) there are separate words for these two meanings. By using the word free as a key in multiple places with different meanings it would be impossible to correctly localise the text to German.
* The original text might change through an update (fixed spelling mistake is an obvious use-case here). If the text is used as key that breaks the connection between the text in the original content file and the updates content file and therefore forces the translator to figure out what is going on and then make manual corrections.
Instead we use an ID based scheme. We add a new type of record (localisation) that contains as a single field the localised text.
In legacy content files user visible text is contained in other records. On loading of these files we move this text out of these records and into separate localisation files. The ID of the localisation record will be generated from the ID of the other record with a suitable suffix (e.g. $name).
By factoring out all user visible text into a separate record type we make it possible for the editor to present the text to the translator in a single table.
We will allow the editing of the localisation record within the UI (table or dialogue) of the main record, so that for a content developer who is not involved in localisation the workflow is not being made more complicated.
## Fallback-Strings
The openmw.cfg file contains a collection of fallback strings that were taken from Morrowind.ini. No localisation mechanism is provided (other than swapping out Morrowind.ini files).
OpenMW uses these strings only when loading older content files. However "older" is a less specific term here than throughout the rest of this document. As OpenMW progresses through feature releases we will continue to add new user visible strings (e.g. labels for new user settings). Therefore we will need a fully functional localisation system for fallback strings alongside the primary record-based localisation system.
We will allow an optional language-code prefix (lp) in the key:
````
fallback-lp-somekey=Some Text
````
When looking up fallback strings the preferred language is chosen by the default language setting in the launcher (we may decide to provide a separate setting for fallback strings if this doesn't result in an overly complicated settings UI).
If a fallback string with this language-code is available it will be used. If no such fallback string is available, the default fallback string (without language-code prefix) will be used. The default fallback string must exist for all fallback strings with language codes. Otherwise the cfg file must be considered defective.
We add an option to the importer tool to import strings only, which then will be merged (with a user-specified language-code prefix) into an existing cfg file.
Non-legacy fallback strings (added after 1.0) will be added to the global cfg file instead. We will accept localised versions of these strings provided by the community. Since these strings are not part of vanilla MW, there are no legal issues with including these strings in the official repository.
## Cell Names
The handling of cell names in vanilla MW is one of the major localisation problems that need to be addressed post 1.0. Cell names are used both as the text that is presented to the user and as the internal identifier by which cells are referenced. This is further complicated by a system that allows the use of partial names.
We turn the name field (the ID) into an ID-only field. The actual user visible name is moved into an optional localisation record.
This change does not fix the problem of already existing localisations that have modified the names of cells. See the section about localisation mapping below for a workaround.
## Topics
The situation with dialogue topics is similar to the cell situation and we will apply the same fix, though with a minor modification.
When referencing a topic by the localised text (instead of the ID) from within a dialogue text (this includes journal entries) we do not emit a warning message. Requiring the use of IDs within the dialogue text would be too much of a burden to the content developers.
## Scripts
Vanilla scripts can contain user visible string literals. This interferes with localisation in an unacceptable way.
User visible string literals within scripts exist in three forms:
1. MessageBox strings
2. Topics (in AddTopic instruction)
3. Cell Names (in various location related instructions)
There is nothing we can do to enforce a solution for #1 without causing unreasonable complications for script authors. But we can at least offer options.
* We add a variant of the new LFormat script function (called just Format) which takes as its first parameter the ID of a localisation record instead of a string literal.
* We add a script function called Text which takes the ID of a localisation record as argument and returns the matching string.
Issues #2 and #3 can be enforced at least partially. We declare the use of user visible strings (instead of IDs) deprecated. For all new script instructions using the user visible string instead of the ID results in an error. Old instructions produce a warning instead.
The new localisation scheme leaves existing localisations unaddressed. Localisations of Morrowind.esm break the connection of cell names and topics in relation to the un-localised Morrowind.esm (English).
We provide a workaround for this problem by introducing localisation mapping. Localisation mapping is a language-specific list of ID/user visible text pairs, provided as a text file. A similar scheme exists for the Russian localisation. We may decide to simple extend the existing implementation of this feature in OpenMW to provide localisation mapping.
Regarding the localisation mapping files two important points need to be considered:
* The files can not be generated automatically. Theoretically we could develop a tool that checks for cell and topic records in two Morrowind.esm files that match in fields other than ID and other user visible text. However this would still require manual checking and seems overall a lot of work for little gain.
* We should not generate and distribute these files within the OpenMW project because of copyright reasons. This task would be left to the modding community.
# GUI
## Argument against general GUI customisation
Under general GUI customisation we understand a fully featured GUI framework that allows content developers to build their own GUI. This is an argument against such an approach.
What are the use cases for a full-scale GUI framework? They seem to fall into two general categories:
1. Alternatives for existing GUI elements (e.g. new inventory system, new load/save GUI, new alchemy GUI)
2. GUI for a completely new game feature that does not exist in vanilla Morrowind
We have handled some instances of case #1 in the OpenMW engine itself already. These seem to do their job and have been well received. It makes sense to continue with this approach and keep this kind of GUI enhancements in the core project instead of handing it over to mod developers. The needs of total conversions in this regard can be met with a skinning system and additional configuration options (see below).
The second case is a little different. If we want enable mod developers to add new skills in the same style as for example alchemy we need a full GUI framework. The question is do we want to encourage this kind of content? Morrowind and also OpenMW are already very heavy on the GUI. A feature set that encourages a lighter use of GUI elements (in favour of more world interactivity instead) could result in overall better content quality.
At a smaller scale the need for interactive GUI features can be fulfilled by individual GUI elements (see below) that can be used from a regular script, similar to multiple choice message boxes.
Note that by going down this route we do not block the addition of a full-scale GUI framework at a later time, if we should decide that we need one after all. All the features described here are useful in general and can be translated into a full-scale solution.
Under the term skinning we understand changes to the look of a GUI without affecting the functionality. Vanilla Morrowind already provides a certain level of skinning-capacity though textures and Morrowind.ini settings. We are going to expand on these and clean up the skinning process. After 1.0 all skinning should be done exclusively through content files and associated resources files. Skinning does not belong in ini/cfg files.
In general we do not need to provide skinning options for individual windows. Instead we aim for a single set of options that are applied to all windows. This will ensure consistency throughout the GUI.
This is a preliminary list of elements that require customisation:
* Window border/furniture textures and sizes
* Text (Font, Colour, Size)
* Window background
* Other Widgets (e.g. Frames)
### HUD
Morrowind (and OpenMW 1.0) has only 4 HUD elements:
* Mini-map
* Active effect list
* Dynamic stats bars with enemy health bar and selected weapon and spell display
* Notifications (non-interactive message boxes)
For all these elements we need the ability to customise the the size and the position (Notifications are a special case here, see below). But we also need to give attention to individual HUD elements (see subsections below).
### Mini-Map
At the very least we should make the width and the height of the mini-map configurable independently from each other. But we also should consider allowing other shapes (maybe defined via a texture).
### Active effect list
We need to make the orientation of the effect list configurable (left, right, down, up).
### Dynamic Stats
Dynamic stats are more complicated since they merge three elements:
* Dynamic stats
* Active weapon and spell
* Enemy health bar
The first two go together well enough, but we should provide an option to decouple the enemy health bar and turn it into its own HUD elements.
We also need to consider that after 1.0 we won't always have three dynamic stats. There could be more or (in stage 2) less. The HUD element must be built in a way that it can adjust its layout accordingly without manual layouting.
Currently we have a single hard-coded notification area (bottom centre of screen), where up to a fixed number of text paragraphs can be displayed in a message box style GUI element.
We introduce a new type of record (NotificationArea) with the following fields:
* Position (top/centre/bottom, left/centre/right)
* Scale
* Maximum number of messages
* Duration factor (scales how long a message stays on screen, depending on the length of the message)
* Message box layout (size, textures)
* Text (horizontal alignment, size)
* Text-Wrap (on or off)
* Default style (see below)
When loading older omwgame files we inject a NotificationaArea record (sys::Messages) that matches the old hard-coded notification area.
We add a new script instructions that replaces the non-interactive variant of the old MessageBox instruction.
* Message text, style = "", area = "sys::Messages"): If style is an empty string, the default style for the notification area is used.
### Notification styles
We introduce a new type of record (NotificationStyle) with the following fields:
* Colour
* Font (including options for bold and italic)
When loading older omwgame files we inject a NotificationStyle record (sys::DefaultMessageStyle) that matches the old hard-coded notification area.
## New Input-Elements
We add a couple of new input elements that are each represented as a separate window:
* Item selection: Takes a list of references and returns the list and an index. List is presented as a horizontal icon view of the items.
* List selection: Takes a list of strings and returns the list and an index. List is presented as a vertical list of text items.
* Numerical input: Takes a range, a precision value and a default value and returns a float.
* Text input: Takes a default value and returns a string.
For each element we add a new script instruction that brings up the respective element. These instructions take the following arguments:
* The input values listed above.
* The ID of a script function that is called when the okay button is pressed
* (optional) The ID of a script function that is pressed when the cancel button is pressed. If this argument is missing (or the ID string is empty) no cancel button is shown.
* Window title text
## Party HUD Element
We add an optional HUD element that shows the status of companions. This HUD element can be switched on/off and configured in the user settings.
For multiplayer we can also show the status of other players. There need to be visual distinction between companions and other players.
## Container Windows
The vanilla Morrowind container windows (inventory, NPC inventory on loot/trade, actual container) has a very poor usability.
Main issues are:
* Icons are not distinguishable enough. Users need to regularly utilise tooltips to identify an item which defeats the purpose of the icon. This problems is caused both by the large number of different items in Morrowind and by the small icon size which does not leave much room for visual differentiation.
* The available tools (item category tabs) are insufficient to manage a large inventory.
We need to improve upon this issue, but we also need to stay close to the original look and feel. We will make three improvements in a way that is as unobtrusive as possible:
### View Modes
We offer three view modes similar to classical file browser:
* Small Icon Grid: The vanilla Morrowind mode. If no small icon is available, we use a down-scaled version of the large icon.
* Large Icon Grid: Like the vanilla Morrowind mode, but with larger icons (at least twice, but probably three times the size). We add a new field to all item type records that contains name of the large icon texture. If no large icon is available an up-scaled version of the small icon is used.
* Table: One line per item (or item-stack). The columns shown are configurable in the user-settings.
The view mode is selected by three buttons that could be placed in the same row as the category tabs.
### Search
We add a search box (either fixed if we can make space for it or as a pop-up). If the search box is not empty only those items are shown those names contain the search string.
### Categories
We make item categories configurable via content files by introducing a new record (ItemCategory) with the following fields:
* Category name
* Item filter
The item filter will be based on item tags (see section Item-Interactions & -Management). These need to be boolean expressions (e.g. tag1 and tag2 or tag3 or not tag4) since a single tag won't allow for enough customisation. Since this is an issue sensitive to scaling (people have large inventories) we should aim for an implementation that is simple and fast.
When loading older omwgame files we inject ItemCategory records for the vanilla categories.
We may explore an alternative GUI layout consisting of a vertical bar (maybe on the right side of the window) that contains an icon for each category instead of text.
The current horizontal text-based category selector is problematic for two reasons:
* Since we hand over the creation of categories to mod developers we can expect a large number of them and therefore scaling becomes an issue. Horizontally arranged text items scale terribly because text items also primarily extend horizontally. There are workarounds for this problem but these are either bad or add alternative interface (e.g. a pull-down menu listing all tabs) which isn't a great solution either. Under no circumstances will we use the workaround that adds two arrow buttons left and right of the tab bar to change the visible section of the tab bar. This is an anti-pattern and everyone who has ever committed the horrendous crime of implementing this GUI-atrocity deserves to end up in usability hell.
If we do use an alternative layout, we need to add an icon field to the ItemCategory record and we also need to consider whether we drop the vanilla one completely or let the user choose. Unless there is strong opposition (this is a significant change from Vanilla after all) we should choose the former option. If we opt for a less radical change we still should switch from text to icons to counter the scaling problem, even if we stick with the horizontal layout.
Currently there is no way to attach additional status information to items or the player character and show these in the appropriate GUI elements.
With record variables we already have the means to store additional stats. We only need a way to indicate to OpenMW that we want to display these stats.
To this end we add a new record type (CustomStat) with the following fields:
* Type (item or character)
* Label
* Tooltip (optional)
* Name of the record variable
Item stats will be shown in the item tooltip. Character stats will be shown on the right side of the character stats window.
We fold bounty value and reputation into this system and inject suitable CustomStat records when loading older omwgame files.
We will also fold skill progression since level up (the number of skill gains for major and minor skills) into this system but without proving a CustomStat record (since this stat isn't displayed in Vanilla). This task is left to content developers (see below).
### Skill Increases
The number of skill increases is an important value for the levelling process. Unfortunately these values are not presented to the player in Vanilla.
We add a new GMST (sys::TrackSkills) of type integer. When loading older omwgame files we inject this record with a default value of 0.
If the GMST is not 0 we show skill progression in two places:
* The tooltip of the skill (number of skill levels gains)
* The tooltip of the attribute (total number of level gains for all skills associated with this attribute)
Random collection of ideas that may be feasible or not:
idea? simple text on instance via a new object type, changeable both during content development and during gameplay via script (e.g. sign post)
idea? celestial de-hardcoding (number of moons, number of suns, custom objects, configurable movement across the sky)
idea? animation de-hardcoding/allow additional animations; possible use-cases:
* more idle animations
* sitting animations
* item handling animations (take a drink from a mug, hold a fishing rod, carry a box)
# Editor
## Scripting
We will use Python as a scripting language for OpenMW-CS. Adding a scripting language is a major task and for stage 1 we will most likely be limited to the basics. More advanced support can be added later.
Sandboxing isn't an issue here, since if we want editor extensions to be useful they can't be sandboxed anyway.
### API
We expose the following API:
* Read-Access to all records
* Read-Access to the content file list
* Read-Access to the resources lists
* Command issuing
### Operation Scripts
We let scripts to run as operations (exclusively for now). In the context of OpenMW-CS the term operation means the following:
* An operation runs in a separate thread and has read only access to the content data
* Multiple operations can run concurrently, but only one operation of each type (e.g. saving, verifier, python script) at a time
* The operation can be terminated by the user at any time
* The operation reports back to the main thread via messages (shown in a table like with the verifier) and progress state (represented as progress bar)
A script operation may issue commands. These commands are queued up and then executed in the main thread once the operation has finished.
The operations script defines the GUI element it is triggered from; either through an API or an associated resource (depending on how we decide to manage Python script in OpenMW-CS).
For stage 1 we allow operation scripts to add menu items to the main menu and to context menus. We will not add a tools main menu item under which scripts are grouped, because this is akin to a misc category, the most useless category of all. We may consider allowing operation scripts to create their own top-level main menu items.
## Debugging
We will expand on the use of OpenMW-CS as a debugging tool. To support this feature we require an easy to use IPC method (preferably platform-independent). Performance is of less importance since we are unlikely to send large amounts of data between OpenMW and OpenMW-CS.
The potential for debugging tools is almost unlimited. But for stage 1 we most likely will only implement some basic tools. Two easily implementable tools with great usability value are listed below.
Note that all debugging tools will require that OpenMW is started from OpenMW-CS.
We add a new keyboard shortcut to OpenMW (only available when started from OpenMW-CS). When used OpenMW will look at the instance under the mouse pointer (or the crosshair if the mouse pointer is hidden). If this instance is part of a content file (i.e. not created during play) OpenMW will send the cell and RefID of the instance to OpenMW-CS. OpenMW-CS inserts the instance info into a table.
This table functions in a similar way to the verifier table; allowing the content developer to jump directly to records that have been identified as being in need of attention.
### Script Error Reporting
OpenMW currently reports script errors and warnings to the console only. When started from OpenMW-CS OpenMW will also send these errors back to OpenMW-CS which will present it in a verifier-like table to the user.
## Namespaces
We will encourage the use of a single main namespace per content file (the content developer is free to add sub-namespaces within this namespace). To this end we will add a namespace field to the content file header.
When adding new IDs the namespace from the header will be inserted into the input field as a default.
We also add function that produces a warning if the user tries to create an ID outside this namespace and outside the special namespaces project, session and default. This function can be disabled via the user-settings. If the content file doesn't have a main namespace (the default for all older content files) this function is inactive.
## Help
OpenMW-CS currently has very little in-application help. Improving this will be an ongoing process. For stage 1 we will focus on scripting.
We will add a keyboard shortcut and a context menu item to the script editor. When activated while the cursor is on a keyword we show a help text that explains the syntax and the function.
The location where we show the help text needs to be determined. For script editor views we could reuse the widget that displays errors. Or we could add a separate subview type for help text. We may decide to add a help main menu item from which the help system can be navigated.
We will add a spell checker by utilising an existing spell check solution. All names (e.g. items, cells, races) will be implicitly added to the list of known words.
Under the term porting we understand the process of moving a content file from one version of a dependency to another version of the same dependency.
At the simplest level this requires only changing the dependency information but we will add additional functions that help with the process.
For the porting of localisation content files (i.e. a new version of a content file is released and the localisation needs to adapt to it) we will add the following functions:
* OpenMW-CS will look up all localisation records that have been added in the new version and present these to the user in a list
* OpenMW-CS will look up all localisation records that have been modified in the new version and present these to the user in a list that shows both the old and the new value
# Misc
This is a random collection of other enhancements that don't fit anywhere else.
## Content User Settings
Currently there is no clean way for content files to provide their own user settings.
To compensate for this shortcoming we introduce a new record type (UserSetting) and a script hook and we rearrange the user settings window.
### UserSettings Record
We add a new record type that describes user settings options. This record type offers several kinds of user settings but does not specify the layout of the GUI elements that are used to represent the settings. We strictly separate the data and the representation (skinning).
User settings data is stored in GMSTs.
A user settings record consists of the following fields:
* slider (type 4): GMST is a float; GUI is a slider; additional data; upper bound, lower bound, default value
### Categories
User settings categories are represented as separate pages/tabs in the GUI. We specify categories via category IDs (strings). Currently there does not appear to be a need for a separate user settings category record, since this record would have no data.
Content files can create new categories (simply by referencing them in a user settings record) or add to existing categories (including the vanilla ones). We should consider adding a couple of additional default categories (including localised labels, but empty and invisible until populated by content files) to help content developers organise their settings in a coherent way.
The categories in vanilla MW are General, Audio, Controls and Graphics. Content files can add settings to these too, but we should consider reorganisation. General is not a good category. We should consider splitting it up. We should also consider moving the key bindings into their own category. A separate key bindings category would have to be the only exception to the rule that content files are allowed to add settings to pre-existing categories.
We add a new hook (sys::SettingsChanged) that is triggered whenever a change to the user settings is mode. The hook function takes a list of strings as argument, containing the IDs of user settings that have been changed.
### Settings Window
The current design of the user settings window in OpenMW is not scalable (it can not accommodate more settings without getting significantly worse). Therefore a complete redesign is required. We should aim for something that resembles the OpenMW-CS user settings window.
This also provides an opportunity to add a GUI to many cfg file only settings that got added prior to 1.0. But we should consider if some of these wouldn't be better suited for bare GMSTs without user setting.
## Launcher Skinning
Currently our launcher has a generic look with some Morrowind branding. This is not desirable for total conversions.
To compensate for this shortcoming we introduce launcher skinning. The launcher skinning is determined by the currently selected omwgame file. We add an new, optional record type that is allowed only in omwgame files.
The exact scope of this new record remains to be determined, but icons and backgrounds are obvious candidates.
## Body of Liquid
Currently we at most have a single body of liquid in each cell that covers the entire cell. This makes it impossible to create additional lakes that are not at sea level.
To compensate for this shortcoming we introduce a new object type: LiquidBody.
Actors within a LiquidBody instance behave in the same way as actors in the regular cell water (drowning, swimming).
A LiquidBody object record has the following fields:
* Liquid ID (see de-hardcoding section, water sub-section)
Shape is a closed Bézier curve that can be edited in the editor. This shape defines a surface (the liquid surface). The depths of liquid body is defined by the height value.
We introduced a fix for a defect in Morrowind.esm by blocking remote access to instances of the object dagoth_ur_1 via mod instructions for dynamic stats. We will now bind this fix to a new integer GMST in the sys namespace. This will allow content developers to disable this fix in their mods (hopefully after giving poor old Dagoth Ur a bit more health).
We add a new optional sub-record to all top-level records. This subrecord contains a string that can be used for writing down notes and additional documentation by content developers.
OpenMW does not need to read these records. If we find that comment subrecords add too much bloat to the record data structures we may decide to skip loading them in OpenMW and even keep them out of the data structures used by OpenMW.
OpenMW-CS will add the comment sub-record as a regular data field. We will provide an option to show the comments as tooltips in various places.
Note that the vanilla esm format already contains a similar field in the land texture record. This field needs to be folded into the new command sub-record.
## No Pause Mode
We add four new GMSTs of type integer (default value 1):
* sys::StatusPause
* sys::DialogPause
* sys::ReadingPause
* sys::CraftingPause
These decide if the game is paused when in status mode (right-click), dialogue mode, journal mode or any of the crafting modes (e.g. alchemy). To handle sys::DialogPause==0 properly we ignore dialogues initiated by NPCs or via script, if the player is already in a dialogue.
We add a new optional field to all object records and instance subrecords, a single enum-like integer.
The value in the object record is considered by OpenMW-CS when creating new instances of that object only (it functions as a default value). OpenMW considers the value in the object record when spawning a new instance during gameplay.
The possible values of the new field are as follows:
* Persistent: Instance can be changed and is included in the save file (this matches the vanilla/OpenMW 1.0 behaviour).
* Transient: Instance can be changed, but is not stored in the save file
* TransientNoSync: Same as Transient; in a multiplayer environment the instance does not need to be synchronised across multiple clients
* Immutable: Instance can not be changed and is not stored in the save file. An attempt to manipulate the instance via a script results in an error. Attempting to spawn an immutable instance into the world also results in an error.
If not present the field defaults to Persistent, except for static objects and instances for which it defaults to Immutable.
The DontSaveObject script instructions (ignored in OpenMW 1.0) can be used to switch a persistent instance to transient state. This function is meant primarily for (marginally) improved backwards compatibility. We do not encourage the use of DontSaveObject for new content.
Immutable statics are a marginal departure from vanilla Morrowind, since statics can be manipulated to some degree. However since that never worked properly in the first place it is not very likely that we break anything and even in case of breakage a quick and simple fix to the content is available. Combined with the large benefits of this feature (drastically reduced save game file size, for one thing) taking the risk of introducing an incompatibility seems worthwhile.
## Multi-Player
OpenMW currently does not support multi-player and is unlikely to do so in the near or intermediate future. But we still can make improvements that aid the multi-player project alongside OpenMW and especially content developers that wish to improve the multi-player experience of their content.
Our goal for multi-player (both in regards to the separate project and if/when multi-player gets integrated into OpenMW) is for content to be usable both in single and in multi-player. This goal isn't fully achievable without special attention from content developers. No matter how we approach multi-player some assumption made by content developers for single-player will be broken, which will then result in some broken content. The best we can hope for is to minimise the breakage.
To this end we will introduce features that will allow content developers to include support for multi-player; mostly in the form of script instructions. These feature must be designed in a way that does not interfere with single-player. Several examples can be found throughout this document.
In the same vein we also provide optimisation options for multi-player, i.e. ways to flag state as not requiring synchronisation across server and clients.
### Content Files
There will always be content files that do not take multi-player into consideration (Morrowind.esm being the obvious case, but some or most current content developers may fall into the same category). This can easily be addressed by putting another content file with fixes on top of the content file (provided the original file had a suitable license).
We will mark up these content files in a similar way as we mark localisations, so that the launcher can automatically match them to their respective main content file and automatically enable them when running multi-player.
### Scripting
Scripting is the biggest issue in regards to multi-player. The current implementation of the multi-player project executes scripts client-side. This is unlikely to work. Anything related to random numbers is an obvious source for (potentially) game-breaking de-syncs. If we dig deeper we will probably find more sources of problems.
On the other hand scripts that contain the ID player can not be executed server-side, because there would be no way to know which player is meant.
The changes required to address these issues are substantial. This is not a task for near future post-1.0 development or even intermediate future development.
What we can do now is to help content developers create their content multi-player ready, so that when multi-player becomes available in OpenMW their content will work out of the box (minus the unavoidable bugs that come from not being able to test content).
### Player
We can have the script engine detect if a script contains the ID player and if that is the case let it execute on the client instead of the server. However that is only a workaround and it is not reliable. Obvious cases where this could fail are:
* Function calls where one of the involved scripts including the ID player and the other doesn't
* The ID player being used not explicitly but via an ID variable.
It would still make sense to implement this workaround as a fallback.
For a proper solution to the problem we need to engineer the scripting language in a specific way and provide guidance to content developers how to use it in a multi-player compatible style.
In particular we need to provide features that allow for the avoidance of the ID literal *Player*.
In some cases the solution is obvious. For example the script slot for OnActivate can pass the activating actor as an argument to the script. Such a script may be able to operate in a more generalised way that does not require an explicit reference to the player. If the script needs to distinguish between player actors and non-player actors it can check the received actor reference against the list of player references.
There are also many script functions that imply the player (e.g. EnableBirthMenu). These must be changed to work on an actor instead.
This is a complex issue that will require more design and deliberation before we can act on it.
