krageon/openmw-tes3coop
1
0
Fork 0
forked from teamnwah/openmw-tes3coop
Code Issues Pull requests Releases Wiki Activity

Merged pull request #896

Browse source
This commit is contained in:
Marc Zinnschlag 2018-05-24 09:49:21 +02:00
commit 1daf8474a4
4 changed files with 526 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

293
docs/cs-manual/source/record-filters.rst Normal file
View file

@ -0,0 +1,293 @@
Record Filters
##############
Filters are a key element of the OpenMW CS user interface, they allow rapid and
easy access to records presented in all tables. In order to use this
application effectively you need to familiarise yourself with all the concepts
and instructions explained in this chapter. The filter system is somewhat
unusual at first glance, but once you understand the basics it will be fairly
intuitive and easy to use
Filters are a key element to using the OpenMW CS efficiently by allowing you to
narrow down the table entries very quickly and find what you are looking for.
The filter system might appear unusual at first, you don't just type in a word
and get all instances where it occurs, instead filters are first-class objects
in the CS with their own table. This allows you to define very specific filters
for your project and store them on disc to use in the next session. The CS
allows you fine-grained control, you can choose whether to make a filter
persistent between session, only for one session or use a one-off filter by
typing it directly into the filter field.
Terms used
**********
Filter
A Filter is generally speaking a tool able to filter the elements of a
table, that is select some elements while discarding others, according to
some criteria. These criteria are written using their own syntax.
Criterion
A criterion describes some condition a record needs to satisfy in order to
be selected. They are written using a special syntax which is explained
below. We can logically combine multiple criteria in a filter for finer
control.
Expression
Expressions are how we perform filtering. They look like functions in a
programming language: they have a name and accept a number of arguments.
The expression evaluates to either ``true`` or ``false`` for every record in
the table. The arguments are expressions themselves.
Arity
The arity of an expression tells us how many arguments it takes. Expressions
taking no arguments are called *nullary*, those taking one argument are
known as *unary* expressions and those taking two arguments are called
*binary*.
Interface
*********
Above each table there is a text field which is used to enter a filter: either
one predefined by the OpenMW CS developers or one made by you. Another
important element is the filter table found under *View* → *Filters*. You
should see the default filters made by the OpenMW team in the table. The table
has the columns *Filter*, *Description* and *Modified*.
ID
A unique name used to refer to this filter. Note that every ID has a
scope prefix, we will explain these soon.
Modified
This is the same as for all the other records, it tells us whether the
filter is *added* or *removed*. Filters are specific to a project instead of
a content file, they have no effect on the game itself.
Filter
The actual contents of the filter are given here using the filter syntax.
Change the expressions to modify what the filter returns.
Description
A textual description of what the filter does.
Using predefined filters
************************
To use a filter you have to type its ID into the filter field above a table.
For instance, try to opening the objects table (under the world menu) and type
into the filters field ``project::weapons``. As soon as you complete the text
the table will show only the weapons. The string ``project::weapons`` is the ID
of one of the predefined filters. This means that in order to use the filter
inside the table you type its name inside the filter field.
Filter IDs follow these general conventions:
- IDs of filters for a specific record type contain usually the name of a
specific group. For instance the ``project::weapons`` filter contains the
term ``weapons``. Plural form is always used.
- When filtering a specific subgroup the ID is prefixed with the name of the
more general filter. For instance ``project::weaponssilver`` will filter only
silver weapons and ``project::weaponsmagical`` will filter only magical
weapons.
- There are few exceptions from the above rule. For instance there are
``project::added``, ``project::removed``, ``project::modified`` and
``project::base``. You might except something more like
``project::statusadded`` but in this case requiring these extra characters
would not improve readability.
We strongly recommend you take a look at the filters table right now to see
what you can filter with the defaults. Try using the default filters first
before writing you own.
Writing your own filters
************************
As mentioned before, filters are just another type of record in the OpenMW CS.
To create a new filter you will have to add a new record to the *Filters* table
and set its properties to your liking. Filters are created by combining
existing filters into more complex ones.
Scopes
======
Every default filter has the prefix ``project``. This is a *scpoe*, a mechanism
that determines the lifetime of the filter. These are the supported scopes:
``project::``
Indicates that the filter is to be used throughout the project in multiple
sessions. You can restart the CS and the filter will still be there.
``session::``
Indicates that the filter is not stored between multiple sessions and once
you quit the OpenMW CS application the filter will be gone. Until then it
can be found inside the filters table.
Project-filters are stored in an internal project file, not final content file
meant for the player. Keep in mind when collaborating with other modders that
you need to share the same project file.
Writing expressions
===================
The syntax for expressions is as follows:
.. code-block::
<name>
<name>(<arg1>)
<name>(<arg1>, <arg2>, ..., <argn>)
Where ``<name>`` is the name of the expression, such as ``string`` and the
``<arg>`` are expressions themselves. A nullary expression consists only of its
name. A unary expression contains its argument within a pair of parentheses
following the name. If there is more than one argument they are separated by
commas inside the parentheses.
An example of a binary expression is ``string("Record Type", weapon)``; the
name is ``string``, and it takes two arguments which are strings of string
type. The meaning of arguments depends on the expression itself. In this case
the first argument is the name of a record column and the second field is the
values we want to test it against.
Strings are sequences of characters and are case-insensitive. If a string
contains spaces it must be quoted, otherwise the quotes are optional and
ignored.
Constant Expressions
--------------------
These expressions take no arguments and always return the same result.
``true``
Always evaluates to ``true``.
``false``
Always evaluates to ``false``.
Comparison Expressions
----------------------
``string(<column>, <value>)``
The ``<value>`` is a regular expression pattern. The expressions evaluates
to ``true`` when the value of a record in ``<column>`` matches the pattern.
Since the majority of the columns contain string values, ``string`` is among
the most often used expressions. Examples:
``string("Record Type", "Weapon")``
Will evaluate to ``true`` for all records containing ``Weapon`` in the
*Record Type* column cell.
``string("Portable", "true")``
Will evaluate to ``true`` [#]_ for all records containing word ``true`` inside
*Portable* column cell.
.. [#] There is no Boolean (``true`` or ``false``) value in the OpenMW CS. You
should use a string for those.
``value(<value>, (<lower>, <upper>))``
Match a value type, such as a number, with a range of possible values. The
argument ``<value>`` is the string name of the value we want to compare, the
second argument is a pair of lower and upper bounds for the range interval.
One can use either parentheses ``()`` or brackets ``[]`` to surround the
pair. Brackets are inclusive and parentheses are exclusive. We can also mix
both styles:
.. code::
value("Weight", [20, 50))
This will match any objects with a weight greater or equal to 20 and
strictly less than 50.
Logical Expressions
-------------------
``not <expression>``
Logically negates the result of an expression. If ``<expression>`` evaluates
to ``true`` the negation is ``false``, and if ``<expression>`` evaluates to
``false`` the negation is ``true``. Note that there are no parentheses
around the argument.
``or(<expr1>, <expr2>, ..., <exprN>)``
Logical disjunction, evaluates to ``true`` if at least one argument
evaluates to ``true`` as well, otherwise the expression evaluates to
``false``.
As an example assume we want to filter for both NPCs and creatures; the
expression for that use-case is
.. code::
or(string("record type", "npc"), string("record type", "creature"))
In this particular case only one argument can evaluate to ``true``, but one
can write expressions where multiple arguments can be ``true`` at a time.
``or(<expr1>, <expr2>, ..., <exprN>)``
Logical conjunction, evaluates to ``true`` if and only if all arguments
evaluate to ``true`` as well, otherwise the expression evaluates to
``false``.
As an example assume we want to filter for weapons weighting less than a hundred
units The expression for that use-case is
.. code::
and(string("record type", "weapon"), value("weight", (0, 100)))
Anonymous filters
=================
Creating a whole new filter when you only intend to use it once can be
cumbersome. For that reason the OpenMW CS supports *anonymous* filters which
can be typed directly into the filters field of a table. They are not stored
anywhere, when you clear the field the filter is gone forever.
In order to define an anonymous filter you type an exclamation mark as the
first character into the field followed by the filter definition (e.g.
``!string("Record Type", weapon)`` to filter only for weapons).
Creating and saving filters
***************************
Filters are managed the same way as other records: go to the filters table,
right click and select the option *Add Record* from the context menu. You are
given a choice between project- or session scope. Choose the scope from the
dropdown and type in your desired ID for the filter. A newly created filter
does nothing since it still lacks expressions. In order to add your queries you
have to edit the filter record.
Replacing the default filters set
=================================
OpenMW CS allows you to substitute the default filter set for the entire
application. This will affect the default filters for all content files that
have not been edited on this computer and user account.
Create a new content file, add the desired filters, remove the undesired ones
and save. Now rename the *project* file to ``defaultfilters`` and make sure the
``.omwaddon.project`` file extension is removed. This file will act as a
template for all new files from now on. If you wish to go back to the
old default set rename or remove this custom file.

62
docs/cs-manual/source/record-types.rst Normal file
View file

@ -0,0 +1,62 @@
Record Types
############
A game world contains many items, such as chests, weapons and monsters. All
these items are merely instances of templates we call *Objects*. The OpenMW CS
*Objects* table contains information about each of these template objects, such
as its value and weight in the case of items, or an aggression level in the
case of NPCs.
The following is a list of all Record Types and what you can tell OpenMW CS
about each of them.
Activator
Activators can have a script attached to them. As long as the cell this
object is in is active the script will be run once per frame.
Potion
This is a potion which is not self-made. It has an Icon for your inventory,
weight, coin value, and an attribute called *Auto Calc* set to ``False``.
This means that the effects of this potion are pre-configured. This does not
happen when the player makes their own potion.
Apparatus
This is a tool to make potions. Again there’s an icon for your inventory as
well as a weight and a coin value. It also has a *Quality* value attached to
it: the higher the number, the better the effect on your potions will be.
The *Apparatus Type* describes if the item is a *Calcinator*, *Retort*,
*Alembic* or *Mortar & Pestle*.
Armor
This type of item adds *Enchantment Points* to the mix. Every piece of
clothing or armor has a "pool" of potential *Magicka* that gets unlocked
when the player enchants it. Strong enchantments consume more magicka from
this pool: the stronger the enchantment, the more *Enchantment Points* each
cast will take up. *Health* means the amount of hit points this piece of
armor has. If it sustains enough damage, the armor will be destroyed.
Finally, *Armor Value* tells the game how much points to add to the player
character’s *Armor Rating*.
Book
This includes scrolls and notes. For the game to make the distinction
between books and scrolls, an extra property, *Scroll*, has been added.
Under the *Skill* column a scroll or book can have an in-game skill listed.
Reading this item will raise the player’s level in that specific skill.
Clothing
These items work just like armors, but confer no protective properties.
Rather than *Armor Type*, these items have a *Clothing Type*.
Container
This is all the stuff that stores items, from chests to sacks to plants. Its
*Capacity* shows how much stuff you can put in the container. You can
compare it to the maximum allowed load a player character can carry. A
container, however, will just refuse to take the item in question when it
gets "over-encumbered". Organic Containers are containers such as plants.
Containers that respawn are not safe to store stuff in. After a certain
amount of time they will reset to their default contents, meaning that
everything in them is gone forever.
Creature
These can be monsters, animals and the like.

168
docs/cs-manual/source/tables.rst Normal file
View file

@ -0,0 +1,168 @@
Tables
######
If you have launched OpenMW CS already and played around with it for a bit, you
will have noticed that the interface is made entirely of tables. This does not
mean it works just like a spreadsheet application though, it would be more
accurate to think of databases instead. Due to the vast amounts of information
involved with Morrowind tables made the most sense. You have to be able to spot
information quickly and be able to change them on the fly.
Used Terms
**********
Record
An entry in OpenMW CS representing an item, location, sound, NPC or anything
else.
Instance, Object
When an item is placed in the world, it does not create a whole new record
each time, but an *instance* of the *object*.
For example, the game world might contain a lot of exquisite belts on
different NPCs and in many crates, but they all refer to one specific
instance: the Exquisite Belt record. In this case, all those belts in crates
and on NPCs are instances. The central Exquisite Belt instance is called an
*object*. This allows modders to make changes to all items of the same type
in one place.
If you wanted all exquisite belts to have 4000 enchantment points rather
than 400, you would only need to change the object Exquisite Belt rather
than all exquisite belt instances individually.
Some columns are recurring throughout OpenMW CS, they show up in (nearly) every
table.
ID
Each item, location, sound, etc. gets the same unique identifier in both
OpenMW CS and Morrowind. This is usually a very self-explanatory name. For
example, the ID for the (unique) black pants of Caius Cosades is
``Caius_pants``. This allows players to manipulate the game in many ways.
For example, they could add these pants to their inventory by opening the
console and entering: ``player- >addItem Caius_pants``. In both Morrowind
and OpenMW CS the ID is the primary way to identify all these different
parts of the game.
Modified
This column shows what has happened (if anything) to this record. There are
four possible states in which it can exist:
Base
The record is unmodified and from a content file other than the one
currently being edited.
Added
This record has been added in the currently content file.
Modified
Similar to *base*, but has been changed in some way.
Deleted
Similar to *base*, but has been removed as an entry. This does not mean,
however, that the occurrences in the game itself have been removed! For
example, if you were to remove the ``CharGen_Bed`` entry from
``morrowind.esm``, it does not mean the bedroll in the basement of the
Census and Excise Office in Seyda Neen will be gone. You will have to
delete that instance yourself or make sure that that object is replaced
by something that still exists otherwise the player will get crashes in
the worst case scenario.
World Screens
*************
The contents of the game world can be changed by choosing one of the options in
the appropriate menu at the top of the screen.
Regions
=======
This describes the general areas of Vvardenfell. Each of these areas has
different rules about things such as encounters and weather.
Name
This is how the game will show the player's location in-game.
MapColour
This is a six-digit hexadecimal representation of the colour used to
identify the region on the map available in *World* → *Region Map*.
Sleep Encounter
These are the rules for what kinds of enemies the player might encounter
when sleeping outside in the wilderness.
Cells
=====
Expansive worlds such as Vvardenfell, with all its items, NPCs, etc. have a lot
going on simultaneously. But if the player is in Balmora, why would the
computer need to keep track the exact locations of NPCs walking through the
corridors in a Vivec canton? All that work would be quite useless and bring
the player's system down to its knees! So the world has been divided up into
squares we call *cells*. Once your character enters a cell, the game will load
everything that is going on in that cell so the player can interact with it.
In the original Morrowind this could be seen when a small loading bar would
appear near the bottom of the screen while travelling; the player had just
entered a new cell and the game had to load all the items and NPCs. The *Cells*
screen in OpenMW CS provides you with a list of cells in the game, both the
interior cells (houses, dungeons, mines, etc.) and the exterior cells (the
outside world).
Sleep Forbidden
Can the player sleep on the floor? In most cities it is forbidden to sleep
outside. Sleeping in the wilderness carries its own risks of attack, though,
and this entry lets you decide if a player should be allowed to sleep on the
floor in this cell or not.
Interior Water
Should water be rendered in this interior cell? The game world consists of
an endless ocean at height 0, then the landscape is added. If part of the
landscape goes below height 0, the player will see water.
Setting the cell’s Interior Water to true tells the game that this cell that
there needs to be water at height 0. This is useful for dungeons or mines
that have water in them.
Setting the cell’s Interior Water to ``false`` tells the game that the water
at height 0 should not be used. This flag is useless for outside cells.
Interior Sky
Should this interior cell have a sky? This is a rather unique case. The
Tribunal expansion took place in a city on the mainland. Normally this would
require the city to be composed of exterior cells so it has a sky, weather
and the like. But if the player is in an exterior cell and were to look at
their in-game map, they would see Vvardenfell with an overview of all
exterior cells. The player would have to see the city’s very own map, as if
they were walking around in an interior cell.
So the developers decided to create a workaround and take a bit of both: The
whole city would technically work exactly like an interior cell, but it
would need a sky as if it was an exterior cell. That is what this is. This
is why the vast majority of the cells you will find in this screen will have
this option set to false: It is only meant for these "fake exteriors".
Region
To which Region does this cell belong? This has an impact on the way the
game handles weather and encounters in this area. It is also possible for a
cell not to belong to any region.
Objects
=======
This is a library of all the items, triggers, containers, NPCs, etc. in the
game. There are several kinds of Record Types. Depending on which type a record
is, it will need specific information to function. For example, an NPC needs a
value attached to its aggression level. A chest, of course, does not. All
Record Types contain at least a 3D model or else the player would not see them.
Usually they also have a *Name*, which is what the players sees when they hover
their reticle over the object during the game.
Please refer to the Record Types chapter for an overview of what each type of
object does and what you can tell OpenMW CS about these objects.

4
docs/source/manuals/openmw-cs/index.rst
View file

@ -21,4 +21,6 @@ few chapters to familiarise yourself with the new interface.
tour
files-and-directories
starting-dialog
tables
record-types
record-filters