Merged pull request #896

docs/cs-manual/source/record-filters.rst

@@ -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.

docs/cs-manual/source/record-types.rst

@@ -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.
+

docs/cs-manual/source/tables.rst

@@ -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.
+

docs/source/manuals/openmw-cs/index.rst

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