Periodical dev to main merge

docs/genome/inventory/index.md

@@ -0,0 +1,29 @@
+# Inventory
+
+The `gCInventory_PS` property set manages the inventory of an entity (such as NPC, Hero or chest).
+The inventory is a list of inventory stacks (`gCInventoryStack`).
+Each inventory stack references a `Template` that is the blueprint for the item contained in the stack.
+The `Quality` and `Amount` of the item is also stored as part of the stack.
+When an item gets equipped to a slot, a physical object with a 3D mesh, physics, and location is spawned in the world and attached to the holding entity (see `Slot` and `Item`).
+The inventory can contain multiple stacks referencing the same template, but with a different quality, equip status or stack type.
+
+Both the category of an item (`gCItem.Category`) and the stack type with which the item gets inserted into the inventory (see also [Treasure Sets](treasure_sets.md)) control in which contexts an inventory stack is visible and usable:
+
+- Regular inventory
+- Trade inventory
+- Plunder inventory
+- Skills
+- Spellbook
+- ...
+
+## Skills and Spells
+The skills and spells that the hero can learn are represented by items in his inventory with the category `gEItemCategory_Spellbook` respectively `gEItemCategory_Skill`.
+
+The `ActivationCount` of a stack is only relevant for stacks containing skills or spells. Its content is related to the `Learned` flag of the stack, because if `ActivationCount` has a value > 0, the skill or spell is activated for the hero.
+
+The difference between the two is important:
+
+- If `Learned` is set to `true`, the hero has permanently learned the skill or spell and can no longer unlearn it.
+- The `ActivationCount`, on the other hand, is always increased by 1 when the hero equips an item that grants this skill or spell as a bonus. When the item is unequipped, the counter is decreased by 1 again. If all items are unequipped, the skills are no longer active for the hero.
+
+Since the hero receives his skills, spells, etc. via code at the start of the game, setting the `ActivationCount` or `Learned` flag for a stack is of no practical use.

docs/genome/inventory/treasure_sets.md

@@ -0,0 +1,127 @@
+# Treasure Sets
+
+Treasure Sets are templates (located in `Templates/Treasure`) that are used to define NPC weapon loadouts, NPC plunder/pickpocket/trade inventories, and the contents of chests.
+Up to five treasure sets can be assigned to an NPC via the `TreasureSet1` to `TreasureSet5` properties of its `gCInventory_PS` property set.
+
+## Plunder Inventory
+
+### gETreasureDistribution_Plunder
+```text
+TransferStacks = Random selection from the interval [MinTransferStacks, MaxTransferStacks]
+
+If TransferStacks < 1:
+    TransferStacks = 1
+
+Repeat TransferStacks times:
+    Stack = Select a random stack from the TreasureSet
+
+    If Stack.Amount > 1:
+        Amount = Random selection from the interval [Stack.Amount / 2, Stack.Amount]
+    Otherwise:
+        Amount = Stack.Amount
+
+    Inventory.Add(Stack.Template, Amount, GetCombinedQuality(Stack), gEStackType_Treasure)
+```
+
+### gETreasureDistribution_Unique
+```text
+Stack = Stack with the lowest gold value among all stacks of the TreasureSet that are not yet marked as already generated
+
+If all stacks are already marked as generated:
+    Stack = Random stack from the TreasureSet
+
+If Stack.Amount > 1:
+    Amount = Random selection from the interval [Stack.Amount / 2, Stack.Amount]
+Otherwise:
+    Amount = Stack.Amount
+
+Inventory.Add(Stack.Template, Amount, GetCombinedQuality(Stack), gEStackType_Treasure)
+
+Mark Stack as generated
+```
+
+### gETreasureDistribution_Trophy
+```text
+Repeat for each stack:
+    If Stack.UseType == gEUseType_TrophyTeeth and the player has NOT learned Perk_TrophyTeeth:
+        Skip stack
+
+    If Stack.UseType == gEUseType_TrophyFur and the player has NOT learned Perk_TrophyFur:
+        Skip stack
+
+    If Stack.UseType == gEUseType_TrophySkin and the player has NOT learned Perk_TrophySkin:
+        Skip stack
+
+    Inventory.Add(Stack.Template, Stack.Amount, GetCombinedQuality(Stack), gEStackType_Treasure)
+```
+
+### gETreasureDistribution_Mining
+```text
+Repeat for each stack:
+    If the player has learned Perk_Mining:
+        Amount = 2 * Stack.Amount
+    Otherwise:
+        Amount = Stack.Amount
+
+    Inventory.Add(Stack.Template, Amount, Stack.Quality, gEStackType_Treasure)
+```
+
+## Trade Inventory
+
+### gETreasureDistribution_Trade_Generate
+```text
+TransferStacks = Random selection from the interval [MinTransferStacks, MaxTransferStacks]
+
+Repeat TransferStacks times:
+    Stack = Select a random stack from the TreasureSet
+
+    If Stack.Amount > 1:
+        Amount = Random selection from the interval [Stack.Amount / 2, Stack.Amount]
+    Otherwise:
+        Amount = Stack.Amount
+
+    Inventory.Add(Stack.Template, Amount, GetCombinedQuality(Stack), gEStackType_Merchandise)
+```
+
+### gETreasureDistribution_Trade_Refresh
+```text
+Repeat for each stack:
+    If Stack.Amount > 1:
+        Amount = Random selection from the interval [Stack.Amount / 2, Stack.Amount]
+    Otherwise:
+        Amount = Stack.Amount
+
+    Inventory.Add(Stack.Template, Amount, GetCombinedQuality(Stack), gEStackType_Merchandise)
+```
+
+### gETreasureDistribution_Trade_NotRandom
+Each stack is generated into the trade inventory in exactly the specified amount. (see also Modder Handbook 1.7.6)
+```text
+Repeat for each stack:
+    Inventory.Add(Stack.Template, Stack.Amount, Stack.Quality, gEStackType_Merchandise)
+```
+## Pickpocket Inventory
+
+### gETreasureDistribution_Pickpocket
+```text
+Stack = Select a random stack
+
+Inventory.AddAndEquip(Stack.Template, Stack.Amount, Stack.Quality, gEStackType_Normal)
+```
+
+## Weaponry
+
+### gETreasureDistribution_Weaponry
+```text
+Repeat for each stack:
+    Quality = Stack.Quality
+    if ( Stack.UseType != gEUseType_Arrow and Stack.UseType != gEUseType_Bolt )
+            Quality |= gEItemQuality_Worn;
+    Inventory.AddAndEquip(Stack.Template, Stack.Amount, Quality, gEStackType_Normal)
+```
+
+Min/MaxTransferStacks do not matter for Weaponry treasure sets. The engine simply processes the full list of stacks contained in the TreasureSet. Also note, that only the first Weaponry treasure set is considered.
+
+If alternative balancing is enabled, once an NPC has been defeated by the hero (`PSNpc::DefeatedByPlayer == true`), that NPC's weaponry is no longer derived from its TreasureSets, but instead the NPC receives a standard weapon that depends on its species (Orc or Human) and political alignment.
+
+

docs/genome/tools/index.md

@@ -8,3 +8,16 @@ Piranha Bytes did not release a modkit for their Genome engine, but the modding
 ## Gothic 3 SDK
 Georgeto, inspired by NicoDE's Risen SDK, has created an SDK for Gothic 3. It can be used to manipulate the engine in the similar way Union is able to manipulate ZenGin.  
 [GitHub repository](https://github.com/georgeto/gothic3sdk)
+
+## g3dit
+g3dit is a world data editor for Gothic 3 that allows you to view and edit .lrentdat, .node, .tple, and several other file types used by Gothic 3.  
+[GitHub repository](https://github.com/georgeto/g3dit)  
+[World of Gothic release thread](https://forum.worldofplayers.de/forum/threads/1330059-Tool-g3dit-Weltdaten-Editor)
+
+## G3IQ
+G3IQ, the Gothic 3 info and quest editor, makes it possible to edit info and quest files, as well as the stringtrable.ini.  
+[World of Gothic download](https://www.worldofgothic.de/dl/download_502.htm)
+
+## g3blend
+g3blend is a Blender addon to import and export Gothic 3 actors (`.xact`) and animations (`.xmot`).  
+[GitHub repository](https://github.com/georgeto/g3blend)

docs/zengin/anims/.pages

@@ -1,3 +1,5 @@
 nav:
+    - naming.md
     - ...
+    - events.md
     - tutorials

docs/zengin/anims/events.md

@@ -61,10 +61,9 @@ General Syntax:
 | [eventSFX](#eventsfx)                 | create sound effect                                                                 |
 | [eventSFXGRND](#eventsfxgrnd)         | create sound effect on the ground                                                   |
 | [eventTag](#eventtag)                 | generic event, does action specified in parameters                                  |
-| Defined in engine but never used ?    |                                                                                     |
 | [eventPFXGRND](#eventpfxgrnd)         | create particle effect on the ground                                                |
 | [eventSetMesh](#eventsetmesh)         | ?                                                                                   |
-| [modelTag](#modeltag)                 | same as eventTag, but applies to morphmesh?                                         |
+| [modelTag](#modeltag)                 | same as eventTag, but applies to all amiations in aniEnum                           |
 
 
 ### eventCamTremor
@@ -125,7 +124,7 @@ Syntax:
 
 Both `INTENSITY` and `HOLD_TIME` can be specified in the MMS script. All gothic morph meshes specify those values in .MMS, therefore behavior when both specified in eventMMStartAni and .MMS file is unknown/untested
 
-## eventPfx
+### eventPfx
 
 Start particle effect at the specified bone. 
 
@@ -155,7 +154,7 @@ Syntax:
     `ATTACH` is used to create demons burning hand during the attack, while without this keyword dust particles are made to stay at the position where NPC landed after falling.
 
 
-## eventPFXStop
+### eventPFXStop
 
 Stops particle effect previously started by [eventPfx](#eventpfx)
 
@@ -177,7 +176,7 @@ Syntax:
 `PFX_HANDLE`        - an integer value. *Handle* of the particle effect, that should be destroyed. Particle effect must be spawned using the same handle by [eventPfx](#eventpfx) first
 
 
-## eventSwapMesh
+### eventSwapMesh
 
 Move mesh from source `NODE` to target node.  Item should be present in the node already. Only mesh of the Items is moved, engine internally still keeps a reference to items in the original slot? Never used in game?
 
@@ -201,7 +200,7 @@ Syntax:
 !!! Note
     In some rare occasions duplicates item 
 
-## eventSfx
+### eventSfx
 
 Play sound effect. It can be either `SFX` instance from scripts, or `.WAV` file.
 
@@ -230,7 +229,7 @@ Syntax:
     A lot of original game animations contain `EMTPY_SLOT` instead of `EMPTY_SLOT` which was probably unintended. Gothic therefore acts as no keyword was provided, which causes a lot of sound interruptions. Therefore be mindful of spelling when copying original MDS scripts
 
 
-## eventSfxGrnd
+### eventSfxGrnd
 
 the same as [eventSfx](#eventsfx) with only one difference, the sound effect name is appended with the current material name.
 
@@ -263,7 +262,7 @@ Depending on the material of the texture, the character is standing on, the game
 NPC running on grass texture, with material set to EARTH in world editor,  will play sound `Run_Earth` by using `*eventSFXGrnd (12 "Run")` in run animation. `_Earth` suffix is determined and added by the engine.
 
 
-## eventTag
+### eventTag
 
 This is a generic type of event that does different actions based on the first parameter after the frame parameter. It was probably later in development to extend MDS functionality without the need to expand parser itself.
 All parameters except `FRAME` are passed inside quotes Further parameters are specific for every `EVENT_TAG_TYPE`. 
@@ -848,27 +847,25 @@ ani	("s_1hAttack"   1   "s_1hAttack"    0.0	0.1	M.  "Hum_1hAttackComboT3_M05.asc
 
 
 
+### eventPfxGrnd
 
-
-## eventPfxGrnd
-
-Not used anywhere in the original game. Could possibly spawn particle effect like [eventPfx](#eventpfx) but with an added suffix similar to how [eventSfxGrnd](#eventsfxgrnd) works. Needs to be investigated.
+Not used anywhere in the original game. Probably meant to spawn particle effect like [eventPfx](#eventpfx) but with an added suffix similar to how [eventSfxGrnd](#eventsfxgrnd) works. In practice, it does nothing.
 
 Syntax:
 ```dae
 *eventPFXGRND (FRAME)
 ```
 
-## eventSetMesh
+### eventSetMesh
 
 Unknown
 
 Syntax:
 ```dae
-*eventSETMESH (FRAME "NODE_NAME")
+*eventSETMESH (FRAME "ASC_NAME")
 ```
 
-## modelTag
+### modelTag
 
 Should work similarly to [eventTag](#eventtag), but can be defined inside aniEnum block and applies to all animations of the Model.