Introduction

Oh hey there! Nice to see you :)

This place will introduce you to the concepts of modding Anomaly, from installing your first mod to creating your own game-changing addons.

Choose a chapter from our table of contents and start reading. I recommend starting with Mod Organiser guide. If you want to contribute - feel free to send your articles (markdown-formatted) per Discord or learn ways to contribute.

Good luck, have fun, don't die

Igigog#6387

Please keep in mind that the book is still being written, and the information provided here may not be accurate, or may not be provided at all!

Meta

Links

Anomaly Discord

Anomaly Modding Book Discord

Acknowledgements

During the development of this book, information was taken from many sites and forums. Here are the main ones:

• Ap-Pro
• AMK-Team
• s.t.a.l.k.e.r mod portal
• GAMERU
• xrWiki
• "Союз Модмейкеров" Discord Server

Also thanks for the advice of individuals:

• Xottab_DUTY#7637 (OpenXRay)
• Daniel(SergeantRogers)#6813 - for providing crash logs

Contributing to this book

First way to contribute

You can easily suggest edits by clicking on the button at the top right

Second way to contribute

This book is written using mdBook. To contribute to this book, you will need:

1. mdBook
2. git
3. GitHub account
4. (Optional) VSCodium

VSCodium or VSCode is highly recommended to use. Although it is optional, I will assume you are using it.

Below I describe the setup steps needed to run and contribute to this book. But before that, go and install VSCodium and Git.

Forking book repository

Contributing to this book follows the standart "Pull Request" workflow. That basically means that you will have your own copy of the book, and you will ask us to pull your changes into the main repository.

Here is the overview of steps needed for contributing:

1. Copy ("fork") the main repository
2. Download your copy of repo
3. Add your changes to your copy
4. Upload your changes
5. Open the Pull Request to merge your changes into main repository

Welp, let's get started. I hope you already have a GitHub account.

Forking

1. Go to the main repo

2. Press the fork button

   

3. Create the fork

   

4. You're awesome

Downloading your repo

1. Open the folder you want to download into in VSCodium. In my case, it will be Desktop.

   

2. Open Poweshell Terminal session

3. Copy the link to your repo.

   

4. Run the following command in your Powershell Terminal with your link instead of LINK.

   git clone LINK
   

5. You're awesome.

Running local copy

1. Download latest mdbook from Github Releases.
2. Drop mdbook.exe in the root folder of your copy.
3. Run run.bat. In case it doesn't open by itself, open localhost:3000 in your browser.
4. Done. You're awesome.

Uploading your changes

1. Set your git up. Here's a great guide

2. Add your changes using VSCodium git tab. Open git tab, hover over "Changes" line and press "+".

   

3. Add a nice message and press "✔" to commit your changes

   

4. You should now be able to publish your changes

   

Creating Pull Request

1. In main book repository, open "Pull Requests" tab and press "New pull request"

   

2. Press "compare across forks". Choose your repository and press "Create pull request".

3. You're awesome. Probably. Now ping Igigog#6387 in Discord to get your pull request reviewed.

4. Done. Your changes are added to the main book.

P.S

If you will be using VSCodium or VSCode, it is recommended to install markdown extensions to make life easier or to avoid messing up the book structure.

For example such as:

• Markdown Link Updater - Updates Markdown links automatically, when files in the workspace are moved or renamed.
• markdownlint - This is a rule library for encouraging standards and consistency for Markdown files.

Getting Started

Installing MO2

This guide is meant to show you how to setup Mod Organizer 2 and how to mod Anomaly in a simple and easy way step by step.

Made by Starcry

What makes Mod Organizer 2 the superior mod manager?

• Installed addons never touch your original game files, instead they are injected into the game only when you boot it up by utilizing virtual file system.

• Mod list is easily manageable, unlike with JSGME you can update or make changes to any addons at any time, without the need of enabling/disabling.

• Shows you which mods are conflicting in details.

Important note: Many antivirus softwares will block MO2 and Anomaly files causing you to have strange crashes, the reliable solution is to scan your MO2 folder for safety, then set an antivirus exclusion to the entire MO2 folder (and to your Anomaly folder).

Installation and instance setup

1. Download the latest version of MO2 (Scroll down, download the .exe and install it)

   

2. After getting this error and clicking "OK" select "Create a portable instance" and press next.

   

   

3. Click "Browse..." and select your S.T.A.L.K.E.R Anomaly folder, name the instance whatever you want and click next.

   Note if you have an error when selecting the game directory: Sometimes MO2 won't detect the game if the directory isn't named "S.T.A.L.K.E.R. Anomaly", in case your problem remains and you have Windows 7 try downloading and double clicking this Windows file.

   

4. The next page will show you where you'r mods and other files for Anomaly mods will be stored, you can leave it as it is and click next.

   

5. Click next again as linking an account to Nexus is not needed.

   

6. After that you should see something like this.

   

7. Congratulations, you paired MO2 with Anomaly successfully. After you click finish MO2 will start up.

Small tutorial

After MO2 boots up you will get 2 popups, one is for an optional tutorial and the other one is for Nexus which we won't need.

In case you skipped the tutorial or didn't fully understand it here's a quick explanation of the most important features:

• Red highlight shows what you need to click to install addons.

• Yellow highlight shows profiles, you can create how many you want and have different mods enabled on each of them.

• Green highlight shows your virtual game directory, this can be useful for checking which file is being used from which addon.

• Blue highlight is used for starting the game, if you don't start your game with this button your mods won't be activated.

Guide to modding and solving conflicts

On the image below you can see how my MO2 looks, I have a little over 100 addons and a lot of conflicts.

After installing few addons you might notice these icons:

• This little lightning icon with a red minus next to it shows that the addon is being overwritten.
• A lightning icon with green plus means the addon is overwriting another addon.
• If you see both of these icons it means the addon is overwriting an addon and is being overwritten by one.
• And last is the grey icon, this icon is next to an addon which is being fully overwritten making it redundant.

To make things work together you need to maintain a load order, that means that you can't just install addons and expect them to all work together, you can start by keeping your load order clean, make some separators (right-click into empty area) like I have in my load order here, after that you can install patches if needed. You can always ask about load orders in the addon-discussion channel.

A good start would be Grok's Community Curated Add-ons List for Anomaly 1.5.1.

Is it better to use a modpack or do everything yourself?

If you are new to modding you might think simply downloading a modpack is the best option, but that might not be the case as most of the time modpacks are the vision of the person who created it - meaning it might have features you won't like and it can be difficult to remove them, you also can't know if it works fine as it's all packed into one folder.

Using a modpack will also mean you won't be able to get help from the community with your crashes as only the modpack creator knows what changes were made and you'll have to rely on them to help you.

Most of the time modpacks aren't being updated frequently and it's near impossible to install any other addon with them.

Solving conflicts

Most of the time it's pretty easy because most popular addons already have existing patches, for example if you wanted to install Boomsticks and Sharpsticks with JSRS you would put BaS first, then JSRS files and then the patch for JSRS that comes with BaS.

Making patches yourself (Not recommended for beginners)

What if there is no patch available and the addons won't work together? You either have to choose which one you want or you can make a patch yourself, the best guide for that is Anomaly modding resource made by community member Jack-it.

Installing addons the right way

Remember that every addon you install needs to have only one gamedata folder, if you find an addon with many optional files you need to install it again every time and select only one gamedata.

As you can see in the picture below I get a popup when trying to install JSRS because it has multiple files, select one and install it, then do it again with the second file (Applies for every addon).

In case you get this popup instead of the one above, you need to expand the filetree and have only option selected, after that you rightclick it and press "set as stalker directory"

In case MO2 crashes when clicking on "manual" addon installation add this text to file ModOrganizer.ini found in Modding/Mo2/:

[CompletedWindowTutorials]
InstallDialog=true

Reporting crashes

Please ignore this if you are using a modpack and report any crashes to the modpack "creator".

If your game crashes and you don't know what caused it go to addon-discussion in Anomaly discord and post your load order along with a log from appdata/logs, it will be a text file named "xray_username".

Converting from JSGME to Mod Organizer 2

To do this you simply have to delete your "gamedata" folder (This will not delete your saves and MO2 will recreate the folder for you) and install the addons you had with MO2, if you don't want to reinstall them you can simply copy the contents of MODS folder to User/AppData/Local/ModOrganizer/Name of your instance/mods.

If you installed addons manually you also need to delete your gamedata folder.

Additional info

If you have any ideas what I should change, fix or add in this guide feel free to ping me on discord (Starcry#4447)

Inspired by lazy stalker guide.

Link to my patreon here ( ͡° ͜ʖ ͡°).

Credits:

• d_nan: did absolutely nothing
• Caesar_salad: also did absolutely nothing

Addon installers

Courtesy of RavenAscendant#7504

MO2 supports 2 kinds of installers. BAIN is the simpler. For BAIN to work you put the gamedata folder for for the main mod into a folder thats name starts with 00. Patches would then go in folders with subsequent numbers. These folders should all be at the root level of the archive.

Example: addon.zip

00 Main
01 BAS patch
02 Optional thing

Files in folders with higher numbers will overwrite those in folders with lower numbers.

BAIN installers present as a list of check boxes. Folders with 00 will be checked by default, all others will be unchecked. Folders at the root of the archive without numbers will not show up in the installer and not be installed.

DNPCAV uses BAIN.

The second is FOMOD Fomod installers can be made to look like a facy windows installer, have preview images, descriptions of what each component does. There is a tool that can help you build a FOMOD installer.

Guide and tool

An anomaly specific Guide

A fomod installer can be built using any folder structure, even the messy one you use now. Or the structure of a BAIN.

Mags Redux has a FOMOD installer but a pretty messy file structure.

SidHUD uses FOMOD but has a BAIN file structure.

Package Naming Guidelines

for Mod Organizer 2

by Ishmaeel

While installing an addon, Mod Organizer 2 can extract a nice name from the archive (ZIP/7Z/RAR):

For more advanced scenarios, you will eventually want to graduate to more powerful installer formats, but for simpler addons, the least you can do for your users is naming your archive package in a way that can be parsed easily by MO2.

Follow these simple rules and your MO2-using audience will be thankful for it:

• Give a descriptive name to your addon.
• Do not separate words with the dash (-) character. Use underscores (_) or spaces. ¹.
• Do not use numbers or special characters in the name.
• Separate extra information such as the version number with a dash (-).
• Do not change the name part in subsequent updates. Only change the “version” part.

¹ We recommend underscores because spaces have other issues in file names and URLs. You can also consider using PascalCase.

MO2 will scan the file name for numbers, special characters and dashes. Everything after the first special character will be stripped by MO2, leaving behind only the name part. If you use any special characters in the middle of your addon name, MO2 Quick Installer will fail to parse the name nicely and your users will end up having to edit the name manually.

Here is a sample file name that includes extraneous information such as a version number:

ToggleScope-v1.5.zip

This is how MO2 will parse the name during installation:

See that everything after and including the dash is stripped away, leaving only the base name.

Note: MO2 will not use the version part at all. The version displayed in the application will be the addon installation date. If you want to explicitly specify a version number, you will have to use BAIN or FOMOD formats.

As long as you adhere to a similar format and keep the same base name, MO2 will recognize your update as belonging to the same addon and offer to upgrade it in place:

The End.

Author's note: The original version of this guide was motivated by annoyance and frustration, so it ended up missing its mark.

For Anomaly Modding Book, we decided to put the actual advice up front in a sarcasm-free manner. You now know the Right Way™ to name your packages.

If you are not interested in the rationale behind this advice or if you do not appreciate snark, feel free to stop reading here.

For a tongue-in-cheek accounting of commonly made mistakes and their grave consequences, proceed to the next section where we have guidance on...

How to Annoy MO2 Users

A Reverse Naming Guide for Mod Authors

Most people do not know about this, but some players prefer to use an obscure piece of software called Mod Organizer 2. In this section, we outline some simple mistakes you can make while naming your addon packages for maximum annoyance of those wimpy persons.

Please note that this guide does not cover how to annoy Chads™ who extract addons directly into gamedata, overwriting whatever is already there. Frankly, we do not think it is even possible to agitate such strong-willed individuals.

MO2 is a tool that enables those who are unable to keep track of several thousand files. It even tries to cleverly extract the addon name from the package name during installation.

Thankfully, there are many ways to subvert this clever mechanism.

Are You an Alpha Modder?

Disclaimer: If your addon has a single-word name such as Addon.zip or a zero-effort name such as New folder.rar, then this guide has nothing to offer you. You are already at the zenith of human annoyingness. You are the ultimate expert in irritation. We bow before your magnifinuisance.

Inconsistent Naming

The fastest takeaway that you can get from this guide is using a different file name for every single release. If you can bring yourself to do this, you don’t need to read the rest of this guide. By default, MO2 will install every new version as a separate addon and the users will have to type out a name for every upgrade if they want a proper installation. It is a surefire way to piss of MO2 virgins:

However, if you feel this one is too on the nose and are looking for subtler ways to annoy the unwashed masses, please read on.

All Characters Are Equal but Some Characters Are More Equal than Others

As mentioned previously, MO2 tries to be clever when determining the addon name from the installation package. To do this, MO2 treats some characters differently.

• Alphabetic characters, underscore and space: These are considered “good” characters for addon naming. MO2 will extract all good characters to generate the default name until it finds a junk character. The rest of the file name is ignored.
• Numeric characters, dash and other symbols: These are considered “junk” characters. MO2 does not think an addon name should include these. Anything after (and including) the first junk character is chopped off and thrown to pigs.

Note: MO2 allows the addon names to start with junk characters, but as soon as a good character is encountered, this exception flies out the window for the rest of the name.

Dashes as Word Separators

You will remember that everything after the first dash is simply discarded. As such, you can use dashes to separate words, so that MO2 will mutilate the awesome and catchy name that you picked for your addon:

This also goes for other fancy characters such as apostrophes. Go crazy!

Numerals: Up Front!

What if you have a cool nickname such as Blaze420 and want to flaunt it in your addon? What if you like putting release numbers first, such as Version 1 of My Awesome Menu Replacement.zip? That’s right. Your MO2-wielding audience is in for a surprise:

Note that if the file name starts immediately with a number, this trick will not work. But good news! If you can manage to sneak the version number in with a cheaty name like 1.0.3_Brooks_Plagiarized_Audio_Patcher.zip, your anemic MO2 users will now have to edit the name with every. single. update!

Pedantic Versioning

You are releasing a new update for your addon with features, bugfixes and localizations? Do not forget to prepend your version number with the letter “v” so that everybody understands what follows is THE VERSION NUMBER!

This will instantly make your file names look more enterprisey and sophisticated:

See the little “_v” at the end? It’s there to bug the MO2-weaklings. Mission accomplished!

Bonus: For even more devious fun, try separating your version number with an “underscore”, so it gets treated as part of the name:

How Not to Smell Like a Filthy UX Hipster

Most importantly, avoid giving descriptive names to your addons and never adhere to a consistent naming format.

If you fail to include one or more of the mistakes above with your every release, those MO2-crybabies will have a minimal-friction upgrade experience, and we don’t want that to happen, do we?

Configuring VSCode-like programs to handle game files

Here will talk about setting up VSCode similar programs to work with game files.

• This article is based on Liner's article on setting up scripts as projects in VSCode
• In this article the setup will be done in VSCodium.

Attention! Not all files can be configured because there are no extensions for their viewing, reading (for example preview .dds textures and others). Some files can only be opened with third-party applications!

Step 1: Installing VSCodium

Just install VSCodium

Step 2. Configuring Extension Associations with a Programming Language

In the settings.json file, in the "files.associations": { specify:

"*.script": "lua",
"*.ps": "hlsl",
"*.cs": "hlsl",
"*.gs": "hlsl",
"*.vs": "hlsl",
"*.s": "lua",
"*.level": "ini",
"*.ltx": "ltx",
"*.seq": "ini",
"*.part": "ini",
"*.part1": "ini"

At the moment these are all the extensions that can be opened in VSCodium

Step 3: Installing extensions

You need to install the following extensions:

1. audio-preview by sukumo28 - provides more detailed data about the sound files. Needed for .ogg files

2. LTX Support by AziatkaVictor - adds support for .ltx files

   • extension can be configured, to do this in his settings need to specify the path to the scripts of the game
   • More About

3. Two extensions for Lua. Needed for .script files:

   • LUA by keyring

   • LUA by yinfei

   • You need a fully unpacked scripts folder to work. You also need to create a workspace for your project. Some files will always give error warnings (e.g. lua_help - This can be deleted or added to exceptions in the extension from yinfei)

4. Open in External App by YuTengjing - ability to open the file in other applications. Needed for .ogf, .object, .dm, .omf, .dds, .thm, .ogm files

   • The extension can be configured by writing in settings.json in the "openInExternalApp.openMapper": [ needed programs. Example:

   "openInExternalApp.openMapper": [
   
    // 3D models (ogf, dm, object)
        {
            "extensionName": "ogf",
            "apps": "D:\\Нужное\\Modding Tools\\OGF.Editor\\OGF tool.exe"
        },
        {
            "extensionName": "object",
            "apps": "D:\\Нужное\\Modding Tools\\Object.Editor.4.35\\Object tool.exe"
        },
        {
            "extensionName": "dm",
            "apps": "D:\\Нужное\\Modding Tools\\OGF.Editor\\OGF tool.exe"
        },
    // Textures (thm, dds)
        {
            "extensionName": "thm",
            "apps": "D:\\Нужное\\Modding Tools\\THM_Editor_by_ValeroK\\THM Editor.exe"
        },
        {
            "extensionName": "dds",
            "apps": "C:\\Program Files\\paint.net\\paintdotnet.exe"
        },
   
    // Video
        {
            "extensionName": "ogm",
            "apps": "C:\\Program Files\\VideoLAN\\VLC\\vlc.exe"
        },
    // Animations
        {
            "extensionName": "omf",
            "apps": "D:\\Нужное\\Modding Tools\\OMF.Editor.1.2\\OMF_Editor.exe"
        },
    ],
   

5. HLSL support and preview for shaders:

   • Shader languages support for VS Code by slevesque
   • HLSL preview by A2K

6. TGA Image Preview by lunarwtr - Preview .tga files

DLTX

Written by @nltp_ashes

1. About

Modding STALKER has this annoying tendency to result in conflicts when two different mods overwrite the same .ltx file, but not the same variables and sections within that file.

DLTX aims to mitigate this by allowing a mod author to only override the values that they actually wish to change in a separate file, which should greatly reduce the amount of needless mod conflicts and the need to manually merge mods.

2. Installation

DLTX is built-in the Anomaly Modded Exes.

• Download the file STALKER-Anomaly-modded-exes.zip from this repository;
• Back up the contents of your "bin" folder;
• Unpack the contents of the archive on top of your game's root folder.

3. Tools

To make the process easier for people uncomfortable with DLTX, or to automatically DLTX-ify older addons, you can use the LTXDiff tool.

LTXDiff findroot

In order to properly DLTX-ify a file, you need to find its root file. For this, you can either manually trace back the chain of #includes, or use the LTXDiff.

In order to make a differential change to the LTX records, you have to follow these steps:

Step 1 : Find the root file

Execute the following command :

LTXDiff findroot "[Base Folder]" "[Mod Folder]" "[Relative Path to File]"

Where :

• [Base Folder] : A path to the unpacked vanilla files of the game;
• [Mod Folder] : A path to your mod's folder;
• [Relative Path to File] : A path relative to gamedata/ to the file you wish to find the root of.

For example :

LTXDiff findroot "C:\Games\Anomaly\tools_unpacked" "C:\Mods\MyMod\gamedata" "configs\items\items\items_repair.ltx"

Step 2 : Create your DLTX file

Once you have found the root file, create a new file in the same directory with the name :

mod_[Root File Name]_[Mod Suffix].ltx

Where :

• [Root File Name] : The name of the root file you identified via Step 1;
• [Mod Suffix] : A unique name (as to not conflict with other addons) of your liking;

For example :

mod_system_my_name_jeff_addon.ltx

Step 3 : Write your DLTX edits/additions

Apply the changes or additions of your liking. See syntax chapter for more details.

LTXDiff dltxify

LTXDiff is capable of automatically converting conventional mods into a DLTX-ready format.

If you're lucky, the DLTXify by right click might work for you. Instructions about it are available on the addon's page. Alternatively, you can use LTXDiff dltxify.

Execute the following command :

LTXDiff dltxify "[Base Folder]" "[Mod Folder]" "[Mod Suffix]"

Where :

• [Base Folder] : A path to the unpacked vanilla files of the game;
• [Mod Folder] : A path to your mod's folder;
• [Mod Suffix] : The unique name you want to be used for your addon's file.

4. Syntax

The following table connects the different symbols used by DLTX to their corresponding feature(s).

Section override

To override a section, you use the ! symbol before the section declaration.

To override the section called some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

![some_section]

Please note :

• this alone does nothing, and needs to be used in combination with other things;
• when you override a section, you do not list again the parent sections inheritance.

Section deletion

To delete a section, you delete all the section's fields, and you use the !! symbols before the section declaration.

To delete the section called some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

!![some_section]
!price
!weight
!friends

Section creation/override

To create a section if it doesn't exist, or override it if it already exists, you use the @ symbol before the section declaration.

To create/override the section called some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

@[some_section]

Please note :

• this alone does nothing, and needs to be used in combination with other things;
• this only exists in the Anomaly 1.5.2 version of the Modded Exes.

Section inheritance addition

To add a new parent section to another section, you add the new parent as you normally would, without listing all the existing parents again.

To add the some_other_section section as parent of some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

![some_section]:some_other_section

Section inheritance deletion

To remove a parent section of a section, you prefix the parent section you wish to remove with the ! symbol in the list of parents.

To remove the parent_section section from the parent of some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

![some_section]:!parent_section

Field override

To override a field within a section, you override its section and you redefine the field.

To override the field called price in some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

![some_section]
price       = 10000

Field deletion

To delete a field within a section, you use the ! symbol before the field declaration.

To delete the field called price in some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

![some_section]
!price

Field CSV list addition

To add an item in a CSV list, you use the > symbol before the field declaration, and list the elements you want to add.

To add the item you in the field called friends in some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

![some_section]
>friends    = you

Please note :

• do not list again the elements already present in this list;
• this only exists in the Anomaly 1.5.2 version of the Modded Exes.

Field CSV list deletion

To remove an item from a CSV list, you use the < symbol before the field declaration, and list the elements you want to remove.

To remove the item myself in the field called friends in some_section :

[some_section]:parent_section
price       = 5000
weight      = 1.0
friends     = me, myself, i

You use :

![some_section]
<friends    = myself

Please note :

• do not list again the elements already present in this list;
• this only exists in the Anomaly 1.5.2 version of the Modded Exes.

Sources

Modded Exes (contains DLTX)

Legacy page for DLTX on Moddb

LTXDiff Source Code

DLTXify by right click

DXML

Intro

DXML by demonized#1084

DXML is a part of modded exes repo

DXML allows to manipulate XML files before they loaded into the engine or scripts by utilizing Lua The engine sends XML string to Lua where it is transformed into DOM-like object (from now on lets call it xml_obj) that can be manipulated by Lua methods and then it is converted back to XML string and sent back to engine

To use it in your mods, you have to create a new script file that is called modxml_<yourname>.script. The yourname can be any string, it doesnt matter. The "modxml_" part must be in the filename.

Then, in this file, type:

function on_xml_read()
    RegisterScriptCallback("on_xml_read", function(xml_file_name, xml_obj)
        -- XML file i want to change
        local xml_to_change = [[text\eng\_game_version.xml]]

        -- Check if its the file i want to change
        if xml_file_name == xml_to_change then
            -- Here is my code to change XML
        end
    end)
end

What this does is creating a function on_xml_read that will be auto-called from dxml_core.script. This function will register function for new callback "on_xml_read", which accepts two arguments:

• xml_file_name - current XML filename that engine is processing (for example: text\eng_game_version.xml)
• xml_obj - the object described above

WARNING: DXML won't process translation strings other than from eng/rus folders and gameplay\character_desc_general.xml file. For how to manipulate that file check "Additional functions" paragraph below.

To understand, what can be done with xml_obj and what functions it provides, let's take a look at typical usecases:

Case 1: inserting new XML data

Examples: insert new dialog into gameplay\dialogs.xml, insert new scope texture into ui\scopes.xml

This is the simplest case of using DXML, where you just want to insert new data, much like #include directive in XML files

To do this, you can use xml_obj:insertFromXMLString function as in example below:

function on_xml_read()
    RegisterScriptCallback("on_xml_read", function(xml_file_name, xml_obj)
        -- XML file i want to change
        local xml_to_change = [[ui\scopes.xml]]

        -- Check if its the file i want to change
        if xml_file_name == xml_to_change then
            -- Here is my code to change XML
            local my_new_scope = 
[[
<wpn_crosshair_bino x="0" y="0" width="2048" height="1536">
    <auto_static x="0" y="0" width="1024" height="768" stretch="1">
    <texture>wpn_crosshair_bino</texture>
#include "gameplay\character_criticals.xml"
    </auto_static>
</wpn_crosshair_bino>
]]
            xml_obj:insertFromXMLString(my_new_scope)
        end
    end)
end

This example adds new scope texture into scopes.xml. DXML supports #include directive to include other xml files into string. #include must start from the beginning of the line like in the example. (BTW: For actually adding new scope you don't need include anything, its just an example. The #include is necessary when working with adding new special npcs or such)

insertFromXMLString method has these arguments:

• "xml_string" - XML string to process
• "where" - the element in xml_obj in which new data will be inserted argument is optional and specifies an element subtable of self.xml_table to insert (default - root element)
• "pos" argument is optional and specifies position to insert (default - to the end)
• "useRootNode" argument is optional and will hint DXML to insert contents inside the root node if it has one instead of whole string

The function returns the position of first inserted element in "where"

Case 1.1: inserting new XML data from file

Examples: insert new dialog into gameplay\dialogs.xml from file plugins\new_dialog.xml

This case will insert new data from a xml file plugins\new_dialog.xml into gameplay\dialogs.xml.

To do this, you can use xml_obj:insertFromXMLFile function, where you specify the path to the file and the arguments, which are exactly the same as in xml_obj:insertFromXMLString function.

The path argument should be a path to the file WITH EXTENSION (example: [[plugins\new_dialog.xml]]).

The base folder for xml files to read is gamedata/configs, for example if the path provided is plugins\new_dialog.xml, then the file should exist in gamedata/configs/plugins/new_dialog.xml.

If the file has failed to read, the game will crash with the error message displaying what happened.

function on_xml_read()
    RegisterScriptCallback("on_xml_read", function(xml_file_name, xml_obj)
        -- XML file i want to change
        local xml_to_change = [[gameplay\dialogs.xml]]

        -- Check if its the file i want to change
        if xml_file_name == xml_to_change then
            -- Here is my code to change XML
            xml_obj:insertFromXMLFile([[plugins\new_dialog.xml]])
        end
    end)
end

Case 2: inserting new XML data in specified element

Example: insert new menu item into ui\ui_mm_main.xml

In order to correctly insert new main menu item, we need to find the <menu_main> element first.

To find an element, you can utilize CSS-like selectors in query function. An example of finding <menu_main> element would be:

local res = xml_obj:query("menu_main")

The function returns a table with all found elements matching this query.

The element is represented by table with following fields:

• el = element type, consists of type symbol, name and attributes. The type symbols are:
  • "<" - node element
  • "#" - text element
• parent = pointer to a table that contains this element
• kids = table that contains all children of this element

Then we check if table is not empty (the element exists) and insert our xml string with new menu item in position before the end

if is_not_empty(res) then
    local el = res[1]
    xml_obj:insertFromXMLString([[<btn name="btn_mcm" caption="ui_mm_menu_mcm"/>]], el, #el.kids)

Full code would be:

function on_xml_read()
    RegisterScriptCallback("on_xml_read", function(xml_file_name, xml_obj)
        -- XML file i want to change
        local xml_to_change = [[ui\ui_mm_main.xml]]

        -- Check if its the file i want to change
        if xml_file_name == xml_to_change then
            -- Here is my code to change XML
            local mcm_menu = [[<btn name="btn_mcm" caption="ui_mm_menu_mcm" />]]
            local res = xml_obj:query("menu_main")
            if is_not_empty(res) then
                local el = res[1]
                xml_obj:insertFromXMLString(mcm_menu, el, #el.kids)
            end
        end
    end)
end

But, if there is already an MCM menu, then you might get duplicated element inside. So we have to check if its already exists before insertion. We can check if element <btn name="btn_mcm"> exists before proceeding by utilizing query again.

Here, similar to CSS, we want to find <btn> element with attribute name="btn_mcm" first. if its found - then make early return from the function

    if is_not_empty(xml_obj:query("menu_main btn[name=btn_mcm]")) then
        printf("MCM button already exists")
        return
    end

Full list of available CSS-like selectors are:

• " " (space) - find children of elemenents (can be any depth inside)
• ">" - find direct children
• "+" - find first sibling of element
• "~" - find all siblings
• "[attr1=value1]" - describes attribute attr1 with value value1. To find element that matches multiple attributes you can use [attr1=value1][attr2=value2] and so on

Case 3: Change text inside element

Example: change text of game version in text\eng\_game_version.xml

Getting and setting text is possible if element contains raw text inside, like <text attr1="value1">My Text</text>. To get text, you can use getText(element) function and to set it use setText(element). Example below of appending text to existing text in element

function on_xml_read()
	RegisterScriptCallback("on_xml_read", function(xml_file_name, xml_obj)
		if xml_file_name == [[text\eng\_game_version.xml]]
		or xml_file_name == [[text\rus\_game_version.xml]]
		then
			-- Find string element with "id=ui_st_game_version" text inside it
			local res = xml_obj:query("string[id=ui_st_game_version] > text")
			if res[1] then
				local el = res[1]
				local el_text = xml_obj:getText(el)
				if el_text then
					-- Set new text
					xml_obj:setText(el, el_text .. ". Modified exes (DLTX, DXML, Shader Scopes, SSS)")
				end
			end
		end
	end)
end

Case 4: changing attribute of element

Example: change position of money display in ui\ui_inventory.xml

First, find <money> element inside <player> element and then change its x, y attributes by using setElementAttr function

setElementAttr(el, args)

• el - element found using query
• args - table of attributes ({attr1 = value1, attr2 = value2})

To get attributes of element, use getElementAttr function, it returns a table of attributes described above

getElementAttr(el)

• el - element found using query

To remove attributes of element, use removeElementAttr function

removeElementAttr(el, args)

• el - element found using query
• args - list of attributes to remove ({attr1, attr2})

function on_xml_read()
	RegisterScriptCallback("on_xml_read", function(xml_file_name, xml_obj)
		if xml_file_name == [[ui\ui_inventory.xml]]
		then
			local res = xml_obj:query("player > money")
			if res[1] then
				local el = res[1]
				xml_obj:setElementAttr(el, {x=20, y=60})
			end
		end
	end)
end

Full list of methods is described in dxml_core.script in COnXmlRead function

Additional functions

For now, it is impossible to use xml_obj from DXML to process gameplay\character_desc_general.xml. This file includes all information about generic NPCs you see in the Zone (name, bio, community, etc). As an alternative, DXML provides additional callbacks in this case.

on_specific_character_init

on_specific_character_init callback provides possibility to change NPCs' data. An example on how to use it:

function on_game_start()
    RegisterScriptCallback("on_specific_character_init", function(character_id, data)
  
        --character_id is the id attribute of <specific_character> tag (ie. "sim_default_csky_0_default_0")
        if character_id == "sim_default_csky_0_default_0" then
  
            -- change appearance of this npc to Beard
            data.visual = "actors\stalker_neutral\stalker_neutral_3_face_1"
        end
    end)
end

Full list of fields available in "data" table:

• name
• bio
• community
• icon
• start_dialog
• panic_threshold
• hit_probability_factor
• crouch_type
• mechanic_mode
• critical_wound_weights
• supplies
• visual
• npc_config
• snd_config
• terrain_sect
• rank_min
• rank_max
• reputation_min
• reputation_max
• money_min
• money_max
• money_infinitive

on_specific_character_dialog_list

on_specific_character_dialog_list callback provides possibility to change available dialogs for NPCs. The callback sends character id and dialog list class object, that can be used to manupulate available dialogs. An example on how to use it:

function on_game_start()
    RegisterScriptCallback("on_specific_character_dialog_list", function(character_id, dialog_list)

        --character_id is the id attribute of <specific_character> tag (ie. "sim_default_csky_0_default_0")
        if character_id == "sim_default_csky_0_default_0" then

            -- Add dialog about playing Blackjack
            local res = dialog_list:add("cit_killers_minigame")

            if res then
                printf("adding dialog %s for %s, pos %s", "cit_killers_minigame", character_id, res)
            end
        end
    end)
end

Full list of methods in dialog_list

• find(regex) - find existing dialog by regex, returns last found dialog matching regex and its position in the list
• has(string) - check if dialog by string exists, returns the position of found dialog in the list
• add(string, pos) - adds new dialog in specified position (by default adds before break dialog string if it exists)
• add_first(dialog) - adds dialog in the beginning of the list
• add_last(dialog) - adds dialog in the end of the list
• remove(string) - removes dialog by the string
• get_dialogs() - returns the list of all dialogs available

PS

See dxml_core.script for all methods and callbacks available

MCM

"The greatest victory is that which requires no battle." - Sun Tzu

Ask Raven to write about it, not my mod. - Igigog 2022

His handle is RavenAscendant#7504 just in case you need it for... things ^^

Monkey patching

Courtesy of RavenAscendant#7504

All code snippets used in the guide are licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License

This guide is specifically written for modding Anomaly. Much of it will apply with minor changes to any STALKER modding. The concept is not limited to STALKER or even lua, Minecraft modding makes extensive use of monkey patching in Java.

Monkey patching is the practice of modifying code at run time. Instead of modifying the script file directly the modifications are done in memory by a second script. The primary reason for doing this in Anomaly is compatibility. If two addons are distributed with an edited version of the same Anomaly game script the two addons will be incompatible without patch. Worse than incompatible they will most likely cause crashes if installed together. Monkey patching doesn’t guarantee compatibility, if two addons change the same thing in different ways it is unlikely to behave properly, however the likelihood of crashing is significantly reduced.

First a caution, it is always better to simply use call backs. There are a significant number of call backs that allow you to change the way Anomaly plays. Editing Anomaly scripts directly or by monkey patching should only be done if there is no other way. Once one script starts changing the flow of another it becomes significantly harder to figure out what is actually going on.

In general Anomaly scripts are loaded in alphabetical order. When you monkey patch a script that hasn’t loaded you force it to load. If two monkey patches are applied the script that comes last wins. Starting the name of your script with a z means that it will load after most other scripts. While only sometimes necessary and very rarely problematic, the strong suggestion to do so in an earlier version of this guide has resulted in a convention of starting monkey patch scripts with z or zzz.

If a function or variable in a script is declared as local other scripts can’t manipulate it. None of the below techniques will work on local functions or variables.

Patching Variables

The simplest monkey patch only changes variables. Instant tooltip does this. It uses a callback to watch for the inventory UI being opened and when it is changes the delay for the tool tip:

function on_game_start()
    RegisterScriptCallback("GUI_on_show", delay_change)
end


function delay_change(name, path)
    --return quickly if not the GUI we want
    if not (name ~= "UIInventory")  then return end

    ui_inventory.GUI.item_info.delay = 80
    ui_inventory.GUI.upgr_info.delay = 80
end

The changes can be far more complex, an example of reaching into a complex nested table is how SidHud adds itself into the game settings UI with its inject_options_UI() function.

Patching existing Callbacks

The next method is unregistering a Callback. The most obvious use of this is to stop a game script Callback from being run at all so that you can completely replace its functionality, however there are some more fine tuned uses. The order in which Callbacks from various scripts are run is not something that can be relied upon. If you have something that needs to happen before or after a game script Callback the most reliable method is to unregister the games Callback and then call the function directly from your own Callback at the correct timing. Similarly you can use this method to prevent a Callback from running in particular cases. Such as preventing itms_manager.script from creating a half eaten chocolate bar when a chocolate bar is used:

function on_game_start()
    UnregisterScriptCallback("actor_on_item_use", itms_manager.actor_on_item_use)
    RegisterScriptCallback("actor_on_item_use", test)
end

 function test(obj)
    if (obj:section() == "chocolate") then return end
    itms_manager.actor_on_item_use(obj)
end

The above code has an example of the fact that functions are variables like any other, they can be passed to a function just like a number. They can also be assigned to another variable name just like a number and a function name can be assigned a new value, new code. It is this feature of lua that allows the most powerful monkey patching to work.

Patching Functions

The same way that scriptname.function can be used to call a function in another script it can also be used to save a copy of that function, this can be used to shorten a long function name

ga = utils_item.get_ammo
ga(section, id) -- this is the same as utils_item.get_ammo(section, id)

The scriptname.function syntax can also be used to assign new code (example from first version of Headlamp Animation Fix).

base_Hit_TorchToggle = actor_effects.Hit_TorchToggle

function actor_effects.Hit_TorchToggle()
    local animation_setting = axr_main.config:r_value("options","video/player/animations", 1)
    if animation_setting then
        base_Hit_TorchToggle()
    else
        item_device.toggle_torch()
    end
end

The order there is important. It is necessary to save a copy of the old function first, before you modify it, if you plan on using it later.

Now when any script calls actor_effects.Hit_TorchToggle() it will call the above function instead. It is important to understand that no matter what name you give a function it can only access local variables in the script it is written in.

Patching xray/luajit “classes”

TL;DR: lua oop doesn’t use classes, but, for reasons, X-Ray’s lua does and we can patch either or both the classes or the instance objects. What the : (colon) operator really does. The : operator in lua is simply a shortcut. Any function defined with a : can be called without it.

foo:start()
foo.start(foo)

Those are equivalent.

Similarly a function can be defined without it.

function foo:start()
…
end

function foo.start(self)
…
end

When calling a function the : acts like . but also passes the table to it’s left as an invisible first parameter to the function on the right.

When defining a function : acts like . but also inserts the variable self at the beginning of the parameter list. This syntax allows lua oop to have a familiar syntax.

LUAJit Classes TODO

Some closing notes.

Dealing with local. Sometimes you can get lucky if you dig a bit deeper. Actor_effects.actor_on_item_use is declared local. Not only can you not change it, you also cannot unregister the callback that it is assigned to. However all Actor_effects.actor_on_item_use does is call Actor_effects.play_item_fx(obj:section()) which is not local. Actor_effects.actor_on_item_use can be modified or disabled by patching Actor_effects.play_item_fx. (Be careful tho, that particular function is called from other places as well, and if you don’t want to disable them then you may need to get very creative or are out of luck.)

When it comes to local variables it may be possible to calculate them yourself in your script, this is very easy for constants, harder for things that change, but if you really need to monkey patch yourself into every function that changes that variable and duplicate the calculations before calling the original function, this should keep your copy in step with the original. Watch out for side effects.

If any Anomaly Devs are reading this I strongly recommend that all Callback functions be made not local to allow for unregistering them. TBH i’d like to see local only used for function scoped variables with all globals and functions available from outside the script.

Lua variables unlocalizer

Intro

by demonized#1084

Lua variables unlocalizer is a part of modded exes repo, version 2023.03.09+

This addons allows to unlocalize variables for lua environment, making them global to the script namespace

Usage

• In brackets you define the script file name as a section, without ".script" part

• Under the section put all variables that should be unlocalized, just their names

• Below is the example for actor_effects.script file. RENDERER and STATIC_LIGHT variables are local there, and this file will make them global

• all unlocalizers .ltx files should be put into gamedata/configs/unlocalizers folder

• unlocalizer .ltx'es can be named as you wish, there are no rules there

• Supported local definitions (if local is declared like in the list below, it is possible to unlocalize it)

  • local = (will be transformed to = )
  • local (will be transformed to = nil)
  • local ,, (if any of name1, name2, name3 is in unlocalizers' lists, they all will be unlocalized) (will be transformed to ,, = nil)
  • local ,, = ,... (will be transformed to ,, = ,...)
  • local function <function_name>... (will be transformed to function <function_name>...)

• Unsupported local definitions

  • local x; local y (will be ignored)
  • local x local y (will be ignored)
  • any variations of multiple local keywords on a single line (will be ignored)

Example in gamedata/configs/unlocalizers/unlocalizer_text.ltx

[actor_effects]
RENDERER
STATIC_LIGHT

Useful addons, scripts and utils

DRAGGABLE HUD EDITOR

Allows you to change hud values in weapon hud editor by dragging your mouse

Source

Addon on Moddb

Anomaly Dependencies

Various autoinject script modules for use by other scripts

Source

Source on GitHub

Anomaly Demonized Scripts

Source of not so truthy repo for all uncommon anomaly dependencies

Source

Source on GitHub

Anomaly Addon Dependencies

Various utility scripts of objectionable quality for STALKER: Anomaly

Sources

Source on GitHub

Guides

Stalker Anomaly Resources by Oiltanker

Include:

• ITEM GENERATOR - used as item drops, or other stuff, will generate other items, useful for disassembly to generate custom amounts of stuff

• WORKBECH TOOL AUTO INJECTION + FIXES - fixes some default behaviour and can be used to create recipes with same resulting item or 1 ingredient recipes or add other items as a tool to a recipe

• TERRAIN ENUMERATOR - enumerates spawnable points and caches them into files

Sources

Source on GitHub

Monitor Mod DB

Mod DB comment monitor for addon authors

Source

Source on GitHub

Structure of Files

The files may differ from each other, depending on their purpose, but they all have properties in common.

Note this article describes the structure from CoP or SoC and may not apply to Anomaly!

Section definition

For starters, any information is stored in "sections". These are a kind of objects with a set of parameters, which are usually predefined either by the game engine, if it is some kind of config, or by the scripts, if it is a file responsible for game logic.

Let's take the stalker_sim_squad_novice section of the squad_desct.ltx configuration file as an example:

[stalker_sim_squad_novice]:online_offline_group
faction = stalker
npc_random = sim_default_stalker_0, sim_default_stalker_1, sim_default_stalker_2
npc_in_squad = 2, 3

In this case we can notice the following:

• Definition of the stalker_sim_squad_novice section. Works like a normal variable with similar properties:
  • The name cannot be repeated in the scope.
  • Can have different scopes, depending on the context.
  • It can be referenced if needed to change the section or simply put the information in a separate section (e.g., the meet section).
• Declaring the faction, npc_random and npc_in_squad parameters
• online_offline_group inheritance. Like any other inheritance, it inherits the parent's information, which can be overwritten if desired. In this case it inherits from the file m_online_offline_group.ltx:

[online_offline_group]
GroupControlSection   = spawn_group
class         		= ON_OFF_S
;$spawn          = "scripts\online_offline_group"

Parameter definition

As we discussed above, any section can have parameters. Until now, however, these were just static, simple parameters of the config file. I now propose to parse a slightly more structurally complex parameter from the game logic file:

on_info = {-dont_have_info} %+add_info =play_sound(sound_name)% sr_idle@end

The structure may be confusing at first, but it is quite logical and simple. Let's start by breaking it down:

• Parameter name on_info
• Separator =
• The so-called "Condlist", which will be discussed later, {-dont_have_info} %+add_info =play_sound(sound_name)% sr_idle@end

Definition of Condlist

As written above, the developers have made such a thing as "Condlist". What is it? In essence, it is a kind of block, in which there can be 3 things:

• Condition
• Action
• Value or reference

Example:

{Condition} %Action% Reference

Condition

It is written in {} brackets and is needed to create a condition check so that actions only take place when the condition is met. That is, actions will be executed only when the condition returns True when the "AND" operator is logically executed. You can specify things like:

• Check the presence of infoportion +info_name
• Check for absence of infoportion -info_name
• Checking for a chance of up to 100 in percent ~20
• Function call from xr_conditions.script.
  • If the function name is preceded by =, it is expected to return True. This is exactly the same as function() == True.
  • If the function name is preceded by !, it is expected to return False. This is exactly the same as function() == False.

Example entry, in this case we have this condition:

• Lack of info under the name info1
• Availability of info called info2
• Player has an item called item_name
• Checking that it is not day

{-info1 +info2 =actor_has_item(item_name) !is_day}

Action

It is written in %% brackets and can hold such things as:

• Adding infoportion +info_name
• Removing infoportion -info_name
• Function call from xr_effects.sctript, unlike condition, can only be called with =

Example entry, in this case we have this action:

• Delete info called info1
• Add info called info2
• Issue task_name
• Retrieve item_name

%-info1 +info2 =give_task(task_name) =remove_item(item_name)%

Value or reference

And at the end, a reference or a value. There are no special features here. You can specify things like:

• Reference to the sr_idle@test section. Necessary for some configs and logic. How it works will be described below.
• The value of st_text, true, 10 and so on. Can be used in some configs, when you want to dynamically change the value of parameters. For example, as it is done with tasks in task_manager.ltx
• The keyword is nil. Means "nothing", analogous to null from programming languages. Can be used to specify a value or to end logic.

Feature of use

The main feature of Condlist is that you can specify several Condlists in one parameter. For example:

[hit]
on_info = {=hit_by_actor =hitted_on_bone(head_boss:boss_jaw:brow:ear_r:eye_l:eye_r:) -zat_b106_one_shot} %+zat_b106_one_shot +zat_b108_actor_damaged_chimera +zat_b106_ahtung%, {=hit_by_actor !hitted_on_bone(head_boss:boss_jaw:brow:ear_r:eye_l:eye_r:) -zat_b108_actor_damaged_chimera} %+zat_b108_actor_damaged_chimera%

This is the section from the file zat_b106_chimera.ltx. As we can see, there are two Condlists in the on_info parameter. They are separated by a comma and do the following:

• First Condlist:
  • Condition.
    • =hit_by_actor - damage dealt by the player?
    • =hitted_on_bone(head_boss:boss_jaw:brow:ear_r:eye_l:eye_r:) - damage done to these bones?
    • -zat_b106_one_shot - no info with this name?
  • Action.
    • +zat_b106_one_shot - gives out info with this name
    • +zat_b108_actor_damaged_chimera - gives out info with this name
    • +zat_b106_ahtung - gives out info with this name
• Second Condlist:
  • Condition.
    • =hit_by_actor - damage dealt by player?
    • =hitted_on_bone(head_boss:boss_jaw:brow:ear_r:eye_l:eye_r:) - damage is NOT done to these bones?
    • -zat_b108_actor_damaged_chimera - no info with this name?
  • Action.
    • +zat_b108_actor_damaged_chimera - gives info with this name

In this example, we have no references or variables, because the section implies that we only react when we take damage. So we have only actions and checks here.

Sources

GitHub Wiki Page

Condition Lists Tutorial

Courtesy of tdef#6225 Transfered to modding book by demonized#1084

Condition list or condlist is one way to write dynamic configuration files and have this structure:

somefile.ltx

[some_section]
my_condlist = {=A(a1:a2) !B +C -D ~30} X %=E(e1) +F -G%, Y

and are used like this:

somescript.script

local ini = ini_file("path\\to\\somefile.ltx")
local condlist = ini:r_string_to_condlist("some_section","my_condlist")
local result = xr_logic.pick_section_from_condlist(game_object_1, game_object_2, condlist)

the code above is the equivalent of:

if                                                                  -- {
    xr_conditions.A(game_object_1, game_object_2, {"a1","a2"}) and  -- =A(a1:a2)
    not xr_conditions.B(game_object_1, game_object_2) and           -- !B
    db.actor:has_info("C") and                                      -- +C
    not db.actor:has_info("D") and                                  -- -D    
    math.random(1,100) > 30                                         -- ~30 (not a typo, ~30 means 70% chance, ~80 means 20% and so on)
    
then                                                                -- }
    result = "X"                                                    -- X
                                                                    -- %
    xr_effects.E(game_object_1, game_object_2, {"e1"})              -- =E(e1)
    db.actor:give_info_portion("F")                                 -- +F
    db.actor:disable_info_portion("G")                              -- -G
                                                                    -- %
else                                                                -- ,
    result = "Y"                                                    -- Y
end

Condlist can have more than one condition block:

my_condlist = {-A -B} X, {-A +B} Y, Z

this is the equivalent of:

if                                                                     
    not db.actor:has_info("A") and
    not db.actor:has_info("B")    
then        
    result = "X"
elseif
    not db.actor:has_info("A") and
    db.actor:has_info("B")    
then        
    result = "Y"
else
    result = "Z"
end

All condlist elements are optional, these are all valid condlist:

cond1 =                      ;returns nil
cond2 = true                 ;returns "true"
cond3 = %=f%                 ;returns nil and executes xr_effects.f(a,b) --> remember that a and b depend on the arguments of pick_section_from_condlist 
cond4 = {-info1} , %=f1%     ;if actor doesn't have info1 then returns nil, else returns nil and executes xr_effects.f1(a,b)
cond5 = {+info1} %=f1%       ;same effect of previous one but easier to read

The return value can be ignored to use condlist as a way to run functions listed from a config file, one example are the on_complete lines in task manager files:

on_complete = %=reward_stash(true)%

this condlist has no condition (the part inside {}) and no return value, so calling

xr_logic.pick_section_from_condlist()

on this is the equivalent of just calling

xr_effects.reward_stash(x, x, {"true"})

Remember that both the return on pick_section_from_condlist and arguments passed to xr_conditions and xr_effects functions are strings and not boolean/numbers

Some config lines are condlist even if they aren't obvious, for example one line can be

something = true

but in reality it's a condlist that always returns "true", the only way to know for sure it's to search for "something" in all scripts and see if that config line is parsed as condlist anywhere.

Condlist can be also be parsed from a string

local condlist1 = ini:r_string_to_condlist("some_section","my_condlist")
local somestring = ini:r_string_ex("some_section","my_condlist")
local condlist2 = xr_logic.parse_condlist(game_object, string1, string2, somestring)

condlist1 and condlist2 are the same, the first 3 arguments of xr_logic.parse_condlist are used only to print a message if the 4th (the actual condlist string) is nil, or just use alun_utils.parse_condlist(string)

Now we examine some condlist in Anomaly, what they mean and some examples of edits we can make.

Example 1

near the end of tm_dynamic.ltx in configs/misc

[simulation_task_52]
icon = ui_inGame2_PD_Torgovets_informatsiey
storyline = false
prior = 120
sim_communities = army, bandit, csky, dolg, ecolog, freedom, killer, stalker
repeat_timeout = 14400
precondition = {=random_chance(100)} true, false

title = simulation_task_52_name
descr = simulation_task_52_text
descr_functor = general_fate_desc
job_descr = simulation_task_52_about
task_complete_descr = simulation_task_52_finish

stage_complete     = 4
target_functor     = general_fate
status_functor     = fate_task
condlist_0         = {!task_giver_alive(simulation_task_52)} fail

on_job_descr = %=on_init_fate_task(simulation_task_52:detector_radio:broken_pda:k01_darkscape:k02_trucks_cemetery:y04_pole:l06_rostok:zaton:jupiter:pripyat)%
on_complete  = %=inc_goodwill_by_tasker_comm(simulation_task_52:50) =reward_stash(true) =reward_random_money(10500:18500) =reward_random_item(beer:vodka:vodka2:cigarettes_lucky_3:cigarettes_russian_3) -simulation_task_52_dead_spawned -simulation_task_52_item_spawned -simulation_task_52_target_found =remove_quest_item(simulation_task_52) =forget_dead_npcs(simulation_task_52) =pstor_reset(simulation_task_52)%
on_fail      = %=remove_quest_item(simulation_task_52) -simulation_task_52_dead_spawned -simulation_task_52_target_found -simulation_task_52_item_spawned =forget_dead_npcs(simulation_task_52) =pstor_reset(simulation_task_52)%

if we change precondition line to

precondition = {=is_rain} true, false

then npc will propose this quest only if you ask them while it's raining

if we change it to

precondition = false

then npc will never give this quest

true and false dont have any special meaning in the condlist on their own, in this case they matter only because the code that parses the condlist spelled out by the precondition line does different things depending on the pick_section_from_condlist return value

if we change on_complete to

on_complete = aslkdjslakd %=inc_goodwill_by_tasker_comm(simulation_task_52:50) =reward_stash(true) =reward_random_money(10500:18500) =reward_random_item(beer:vodka:vodka2:cigarettes_lucky_3:cigarettes_russian_3) -simulation_task_52_dead_spawned -simulation_task_52_item_spawned -simulation_task_52_target_found =remove_quest_item(simulation_task_52) =forget_dead_npcs(simulation_task_52) =pstor_reset(simulation_task_52)%

everything will still work as before, because the code that runs the pick_section_from_condlist on on_complete does nothing with the return value, so if it's nil, random text, true/false or whatever doesn't matter

Example 2

inside devushka.ltx in configs/scripts/escape

[walker@devushka]
path_walk = guard_2_walk
path_look = guard_2_look
on_info = {=surge_started} walker@surge
on_info2 = {=is_night} walker@sleeper_1
on_info3 = {=is_rain} walker@rain
combat_ignore_cond = {=actor_enemy =check_enemy_name(actor)} false, false
combat_ignore_keep_when_attacked = {=is_warfare} false, true
reach_distance = 10
gather_items_enabled = false
help_wounded_enabled = false
corpse_detection_enabled = false
invulnerable = {=is_warfare} false, {!actor_enemy} true, false
on_game_timer = 2400 | remark@smoking_stand

we change on_info3 to

on_info3 = {=is_rain =is_actor_enemy_to_faction(freedom)} walker@rain

now Hip will seek shelter from rain only if we are enemy to Freedom, women be like that sometimes

Custom conditions

if you want to make custom conditions either create new functions inside xr_conditions or make your own script file defining functions inside xr_conditions scope

my_conditons.script

function xr_conditions.has_more_money_than(a,b,c)
    
    -- a and b will be the game objects given as arguments to the xr_logic.pick_section_from_condlist call that evaluates this condlist
    -- most of the times a will be the actor game object and b one npc game object, but unless you're 100% sure of that (after testing or looking which pick_section_from_condlist parses it and with which arguments) 
    -- dont ever rely on those, i've seen cases where b is a server object or even nil

    local amount = c and c[1] and tonumber(c[1])
    -- c is a table where condlist arguments for the function are passed
    -- so has_more_money_than(10000) means c[1] == "10000" (a string!)
    -- so we need to convert it to a number to be able to compare it to another
    if amount then
        return db.actor:money() > amount
    end
    return false
end

now we have has_more_money_than available as conditions for condlist, now we can do

on_info = {=has_more_money_than(50000)} walker@surge

so Hip will stay outside during blowouts unless we have more than 50k rubles

you can do the same with xr_effects

my_effects.script

function xr_effects.give_tuna_to_actor(a,b,c)
    alife():create('conserva',vector(),0,0,0)
end

then change on_info2 to

on_info2 = {=is_night} walker@sleeper_1 %=give_tuna_to_actor%

and when Hip goes to sleep you'll get a tuna can

Inventory Icons

Written by @nltp_ashes

Table of content :

• I. Item config
• I.A. Defining an icon sheet
• I.B Placement on the icon sheet
• II. Icon sheet
• II.A. Generalities
• II.B. Setting up icons within the sheet

Items in S.T.A.L.K.E.R. have icons. They are used in the inventory, when picking them off the ground, on the main HUD when attached to the belt, and so on.

This guide aims to help you understand how icons are assigned to an item, how the icon system works, and ultimately, how to properly create your own icons.

I. Item config

Let's start from the end : the item's config. To assign an icon to an item, you need to consider two things. Which icon sheet to use, and where your icon is on this sheet.

I.A. Defining an icon sheet

First, icons textures are contained in icon sheets : textures containing multiple icons. In your item's config, you must (or not) define the icon sheet to use :

File : gamedata\configs\items\items\items_my_item.ltx

[my_item]
icons_texture           = ui\icons\my_icon_sheet
...

In this example, the icons_texture field contains a path, relative to gamedata\textures\ where the game to look for the icon sheet at gamedata\textures\ui\icons\my_icon_sheet.dds.

If you do not define this field, the game will default back to the vanilla icon sheet : gamedata\textures\ui\ui_icon_equipment.dds.

I.B Placement on the icon sheet

Like will be later explained, your icon will be somewhere on this icon sheet. Thus, you need to define the coordinates of the icon on the sheet, and the size of the icon.

File : gamedata\configs\items\my_item.ltx

[my_item]
...
inv_grid_width          = 2    ; how many slots wide it should be
inv_grid_height         = 1    ; how many slots tall it should be
inv_grid_x              = 4    ; where on the grid the icon is on the x axis
inv_grid_y              = 2    ; where on the grid the icon is on the y axis

II. Icon sheet

Now that we understand how the icon sheet is used, it's time to... well, create an icon sheet.

II.A. Generalities

To create and edit your icon sheet, you'll need a specialized software program. Many exist, and it's really up to your personal preferences. I personally use Paint.NET (Free), but you can use GIMP (Free), ImageMagick (Free), Adobe Photoshop (Paid), etc.

First, you will need to create a DirectDraw Surface (.dds) file at the location you defined in the item's config. Here, following the same example, that will be gamedata\textures\ui\icons\ with a file called my_icon_sheet.dds.

For your icons to look good, and have maximum compatibility, you should :

1. Have the x and y resolution of your texture must be a power of 2 : 128x256 or 256x256, etc.;
2. Save the icon sheet, using ARGB8 (also called A8R8G8B8) format;
3. Make the background of your icon sheet should be transparent.

You can think of your sheet as a grid of "slots". Each slot is 50px by 50px. So if you want your icon to be 1 slot, it should be 50px by 50px, two slots vertically 100px by 50px, etc.

Your icon(s) should :

1. Be at least 1 slot wide and 1 slot tall (otherwise there isn't really an icon you know?);
2. Be at most 10 slots wide (that's the width of vanilla's inventory).

II.B. Setting up icons within the sheet

Let us take the following icon sheet as an example.

Note : The black grid is here to help in the explanation, and is of course to be removed before using the icon sheet in-game !

Note 2 : The white background is here to help you see the grid. Your icon sheet should not have a white background !

File : gamedata\textures\ui\icons\my_icon_sheet.dds

You can imagine each slot having a coordinate on this grid. Coordinates start a (0, 0).

File : gamedata\textures\ui\icons\my_icon_sheet.dds

The coordinates for the box of Mon Cheri (the red box in the middle) are for example (4, 2).

File : gamedata\configs\items\my_item.ltx

[my_item]
...
inv_grid_x              = 4    ; where on the grid the icon is on the x axis
inv_grid_y              = 2    ; where on the grid the icon is on the y axis

File : gamedata\textures\ui\icons\my_icon_sheet.dds

The size of the icon is 2 for the width, and 1 for the height.

File : gamedata\configs\items\my_item.ltx

[my_item]
...
inv_grid_width          = 2    ; how many slots wide it should be
inv_grid_height         = 1    ; how many slots tall it should be

File : gamedata\textures\ui\icons\my_icon_sheet.dds

Algoritm of Logic

"Executable" files, game logic files, unlike config files, have an algorithm that, if I'm not mistaken, is based on scripts. The peculiarity of such files is that they have a "Current Section", which defines reactions to interactions with it. Let's look at an example:

[logic]
active = sr_idle@wait

[sr_idle@wait]
on_actor_inside = sr_idle@inside

[sr_idle@inside]
on_info = {=actor_has_item(item)} sr_idle@has_item

[sr_idle@has_item]
on_info = {!actor_has_item(item)} sr_idle@inside
on_actor_outside = nil

The implementation is not the most correct, there are better options, but it is made specifically for demonstration purposes. If we visualize it, it will happen:

Depending on the condition, the object will change the current section. Thus, if the current section is sr_idle@has_item then parameters such as sr_idle@inside will be ignored, because information about other sections besides the current one will be unknown.

Important! Information about the current section is stored in game saves. So if you change your logic, you should check if it works in a new game, because the object will keep its state during the save, and this means the previous sections before the current one will not be called (as shown above, from the sr_idle@has_item section the object will never return to the sr_idle@wait section). This is implemented in the load_obj script from xr_logiс.script.

Now let's look at more complex logic:

[logic]
active = sr_idle@start

[sr_idle@start]
on_actor_inside = {!black_screen} sr_no_weapon@wait

[sr_idle@wait]
on_actor_inside = {=check_smart_alarm_status(pri_a16:normal) !actor_has_weapon} sr_no_weapon@wait
on_info = {=actor_in_zone(pri_a16_sr_light)} sr_no_weapon@wait
on_info2 = {+pri_a28_update_task_cover_strelok -pri_a28_actor_in_zone_stay} sr_idle@wait_stalkers
on_info3 = {+pri_b305_third_cam_go -pri_b305_quest_completed} sr_idle@wait_b305

[sr_no_weapon@wait]
on_actor_outside = sr_idle@wait
on_info = {+pri_a28_update_task_cover_strelok -pri_a28_actor_in_zone_stay} sr_idle@wait_stalkers

[sr_idle@wait_stalkers]
on_info = {+pri_a28_actor_in_zone_stay} sr_idle@wait

[sr_idle@wait_b305]
on_info = {+pri_b305_fifth_cam_end} sr_idle@wait

This logic is already bigger than the previous one, but it is not complicated at all, if you understand it. Now let's visualize it:

I think some have already noticed that there is no action here at all, just changing sections. I dare to suggest that it is about the type of section sr_no_weapon, which prohibits the player to get the weapon. Depending on the condition, the restrictor prohibits or allows the player to take out a weapon, based on the current section.

Sources

GitHub Wiki Page

Scripting

Hey, you. You're finally awake! You were trying to cross the border, right?

So, well, scripting.

Writing scripts for this game is hard, really. You will want to start with Lua book to learn the basics of Lua programming language. I don't know how good it is at teaching general programming concepts, but you surely are brave enough to not concede before a mere programming skill? Right?)

Anyway, the whole programming thing is kinda hard, so feel free to ask questions in Anomaly Discord. Channel #modding-coding is just for you.

Starting here I will assume you know lua. You read the book from start to end and became a master of this programming language. Or at least you know the difference between if and while.

Oh, by the way, code editor. I like Codium, but I know RavenAscendant uses Notepad++ like some old man. For the first couple of scripts you'll be fine with either, choose for yourself.

Introduction to codebase

Prepare for the worst. You'll be either right, or pleasantly surprised.

Codebase. What a nice word for a folder filled with Poorly-But-Sometimes-Good written code. Say hello to our little friend /gamedata/scripts - here you will find every script in the game, and you will even be able to read some of them. Here are the important ones:

1. _g.script - your global namespace. Everything defined here can be accessed in any script. If you don't understand where a function comes from, it's probably here. For example, here lies CreateTimeEvent.

2. lua_help.script - engine imports. It's not really a lua file, but it's important nevertheless. Every namespace defined here is globally accessible, and you better avoid name collisions with it - otherwise death is imminent. Documentation is... Not there, but some names are understandable, so you might be able to use it anyway.

3. axr_main.script - a table with all callbacks is defined there. Don't register your callbacks there, use RegisterScriptCallback from _g instead.

These are the ones you need to know about. Every other functionality is found through global search. Ctrl-Shift-F in your favorite editor. You're welcome.

Codestyle

Every opinion on code style is valid. Mine is not only valid, but also right.

Hehe, I'm joking. Please don't hate me :<

In short, you're free to write your code however you are able to. But there are some guidelines for people to not hate you:

1. Use local functions very sparingly. Local functions are not patchable and represent a major pain in the ass for future maintenance without good benefits. No-no-no, don't start this But Man Locals Give A Performance Boost talk, the difference is marginal and there is no real reason to depend on it.

2. Try to make your functions as understandable as possible - someone will read it. You will, probably, and you will hate yourself in a week after writing bad code. And the whole community will meme on you, so... Don't. Make your variable names give context, make your functions small enough they remain readable and patchable. Feel free to ask in discord, I will slam dunk on your code any day of the week.

3. Try to use monkey patching and callbacks instead of rewriting the main game files. It is possible 90% of time, and addon users will be living their best lives without addon conflicts. Cool? Cool.

That's it. Feel free to be a good boy/girl and write your code so that we'll understand. Good boy. Or girl.

Wetting our hands

At the end of this guide you'll grow enough to be a modder. Just kidding, lol.

Nothing better for a start than actually starting, don't you think?

Who

cares

about

boring

theory.

I sure don't, especially while teaching people.

Let's finally take our script into the game! Go to your favorite Anomaly installation and navigate into gamedata/scripts. Don't have it? Create it. There, create a file my_ingenuous_script.script any way you want. All script files in the folder will be automatically included in the game - cool, right?

Hello, World?

Let's start by showing the player some nice message. Function news_manager.send_tip does wonders in this regard - let's use it! Here is a text for the script:

my_ingenuous_script.script

function on_game_start()
    RegisterScriptCallback("actor_on_first_update", actor_on_first_update)
end

function actor_on_first_update()
    news_manager.send_tip(db.actor, "Your mum gay", nil, nil, 30000)
end

By loading your favorite saved game you will now be shown the state of affairs in the world. You don't see the message? Welp, idk, try again, works on my end.

Let's see how it works:

1. Function on_game_start is always called after loading all the scripts in scripts folder. That happens really early in the loading screen, and the game is not initialised at this point, so we need another time to show the message.
2. Callback actor_on_first_update is fired exactly once after the game is loaded. This is the point in time where the game shows you the "Press any key to continue" in the loading screen, but game session already started, so it's fine.
3. Now we actually send the message in function actor_on_first_update. db.actor is player, 30000 is for how long the message will be shows, everything else is irrelevant.

A little cheating incident

Just showing stuff is no fun, we need Game Mechanics, of course. Lets give player a RPG-8 every time you press "O". Delete everything in your script and write this:

my_ingenuous_script.script

function on_game_start()
    RegisterScriptCallback("on_key_press", on_key_press)
end

function on_key_press(key)
    if key == DIK_keys.DIK_O then 
        alife_create_item("underwear", alife():object(0))
    end
end

Try it out.

Your mighty soaked underwear RPG-8 is waiting for you, you dirty cheater.

You should already know how it goes. Here are the important stuff:

1. Callback on_key_press gives you a key from DIK_keys table. DIK_keys is imported from engine, check lua_help.script for other keys.
2. 0 is the id of actor. alife():object(0) gives you the server object of actor.
3. alife_create_item creates an item inside the inventory of a given server object.

Easy? Easy.

gg go next

Callbacks

I. INTRODUCTION

Callbacks are a convenient and performant way to execute code when certain events occur.

The idea is: you want a function of yours to be executed when something happens in-game, so you subscribe to a callback, and give it your function so that when the event does happen, it can call it back.

There are many callbacks. Most are defined statically in axr_main.script, but some are added by addons dynamically at runtime.

The "main" callbacks (i.e. the most often used ones) are :

1. actor_on_update - A callback called really frequently (almost every frame). In some cases, this is the only way to do what you need, but there is almost always a better option. This callback really isn't performance friendly, so it should be used with extreme caution;
2. save_state (and respectively load_state) - A callback fired when the player saves (and respectively loads) their game. This callback is fired with an argument : m_data, a table in which you can store (and respectively load) any information you want so that it persists in the save game;
3. on_key_press - A callback allowing you to listen to key presses and react accordingly.

There are three functions that exists allowing you to manipulate callbacks :

• RegisterScriptCallback(string, function) - used to register one of your functions to a given callback;
• AddScriptCallback(string) - used to create a new callback at runtime;
• SendScriptCallback(string, ...) - used to fire a callback with arguments.

You must register your functions to callbacks in on_game_start. This function will be called automatically by the game (if it exists in your script) after all scripts are loaded. This is because callbacks need to be created before you can register functions to them. The problem is that, when scripts are still loading, it is possible that not all the dynamic callbacks have been created yet.

function on_game_start()
    RegisterScriptCallback("actor_on_update", my_func)
end

function my_func()
    printf("we are in actor_on_update")
end

II. CREATING CALLBACKS

As previously explained, callbacks can be added dynamically. This means you can create your own callbacks.

To do that, use the AddScriptCallback(string) function (exclusive to Anomaly 1.5.2) to add your new callback. You must do so at the root level of your script, so that other scripts can register callbacks later.

Important : Callback names have a risk of collision, so it is highly recommended you prefix/suffix your callbacks with a unique identifier (like a codename for your addon, or even your nickname - anything that can guarantee no-one else will name their callback the same).

AddScriptCallback("modding_book_something_happened")

Once you have created your callback, you can fire it whenever you want using SendScriptCallback(string, ...). You must specify the callback's name, but after this, you can pass as many arguments as you want. They will be transited to the functions listening for that callback.

In the following example, we will create a callback that fires when the key F is pressed. To make the example more descriptive, it will be split in two files.

File : gamedata\scripts\script_a.script

-- A counter of how many times the player has paid respects
local respects_counter = 0

-- Create the new callback
AddScriptCallback("modding_book_on_pay_respects")

-- Register callbacks
function on_game_start()
    RegisterScriptCallback("on_key_press", some_key_was_press)
end

-- Function called when a key is pressed
function some_key_was_press(dik)
    -- If the key that was pressed is F
    if dik == DIK_keys.DIK_F then
        -- Increase the counter
        respects_counter = respects_counter + 1
        -- Send the newly created callback with the current value of the counter
        SendScriptCallback("modding_book_on_pay_respects", respects_counter)
    end
end

File : gamedata\scripts\script_b.script

-- Register callbacks
function on_game_start()
    RegisterScriptCallback("modding_book_on_pay_respects", is_paying_respects)
end

-- Function called when the player pays respects
function is_paying_respects(respects_count)
    -- print some message in the console showing how many times the player has paid respects
    printf("player has paid respects " .. respects_count .. " times")
end

III. CALLBACKS LIST

The following is a non-exhaustive list of callbacks available in Anomaly 1.5.2.

Technically, this should cover all the callbacks available in vanilla, but remember that addons (like the modded exes) can add additional callbacks too.

Player :
* on_before_level_changing                 Params: ()
* on_level_changing                        Params: ()
* actor_on_before_death                    Params: (<number>,<table>)
* actor_on_net_destroy                     Params: (<binder>)
* actor_on_first_update                    Params: (<binder>,<?>)
* actor_on_update                          Params: (<binder>,<?>)
* actor_on_weapon_fired                    Params: (<game_object>,<game_object>,<number>,<number>,<number>,<number>)
* actor_on_weapon_jammed                   Params: (<game_object>)
* actor_on_weapon_no_ammo                  Params: (<game_object>,<number>)
* actor_on_weapon_lower                    Params: (<game_object>)
* actor_on_weapon_raise                    Params: (<game_object>)
* actor_on_weapon_reload                   Params: (<game_object>,<number>)
* actor_on_weapon_zoom_in                  Params: (<game_object>)
* actor_on_weapon_zoom_out                 Params: (<game_object>)
* actor_on_item_take                       Params: (<game_object>)
* actor_on_item_take_from_box              Params: (<game_object>,<game_object>)
* actor_on_item_put_in_box                 Params: (<game_object>,<game_object>)
* actor_on_item_drop                       Params: (<game_object>)
* actor_on_item_use                        Params: (<game_object>,<string>)
* actor_on_item_before_use                 Params: (<game_object>,<table>)
* actor_on_item_before_pickup              Params: (<game_object>,<table>)
* actor_item_to_belt                       Params: (<game_object>)
* actor_item_to_ruck                       Params: (<game_object>)
* actor_item_to_slot                       Params: (<game_object>)
* actor_on_trade                           Params: (<game_object>,<?>,<number>)
* actor_on_init                            Params: (<binder>)
* actor_on_reinit                          Params: (<binder>)
* actor_on_info_callback                   Params: (<game_object>,<number>)
* actor_on_hit_callback                    Params: (<game_object>,<number>,<vector>,<game_object>,<number>)
* actor_on_attach_vehicle                  Params: (<game_object>)
* actor_on_detach_vehicle                  Params: (<game_object>)
* actor_on_use_vehicle                     Params: (<game_object>)
* actor_on_hud_animation_play              Params: (<table>,<game_object>)
* actor_on_hud_animation_end               Params: (<game_object>,<string>,<?>,<?>,<number>)
* actor_on_hud_animation_mark              Params: (<number>,<string>)
* actor_on_sleep                           Params: (<number>)
* actor_on_foot_step                       Params: (<game_object>,<number>,<?>,<?>,<?>)
* actor_on_interaction                     Params: (<string>,<game_object>,<string>)
* actor_on_before_hit                      Params: (<game_object>,<SHit>,<number>,<table>)
* actor_on_before_hit_belt                 Params: (<table>,<number>,<number>)
* actor_on_weapon_before_fire              Params: (<table>)
* actor_on_feeling_anomaly                 Params: (<game_object>,<table>)
* actor_on_leave_dialog                    Params: (<number>)
* actor_on_stash_create                    Params: (<table>)
* actor_on_stash_remove                    Params: (<table>)
* actor_on_frequency_change                Params: (<number>,<number>)
* actor_on_achievement_earned              Params: (<string>,<string>)
* actor_on_movement_changed                Params: (<number>)
* actor_on_footstep                        Params: (<string>,<number>,<boolean>,<table>)
* actor_on_jump                            Params: ()
* actor_on_land                            Params: (<number>)

NPCs :
* npc_on_use                               Params: (<game_object>,<game_object>)
* npc_on_choose_weapon                     Params: (<game_object>,<game_object>,<table>)
* npc_on_item_take                         Params: (<game_object>,<game_object>)
* npc_on_item_take_from_box                Params: (<game_object>,<game_object>,<game_object>)
* npc_on_item_drop                         Params: (<game_object>,<game_object>)
* npc_on_net_spawn                         Params: (<game_object>,<server_object>)
* npc_on_net_destroy                       Params: (<game_object>)
* npc_on_update                            Params: (<game_object>,<table>)
* npc_on_before_hit                        Params: (<game_object>,<SHit>,<number>,<table>)
* npc_on_hit_callback                      Params: (<game_object>,<number>,<vector>,<game_object>,<number>)
* npc_on_death_callback                    Params: (<game_object>,<game_object>)
* npc_on_fighting_actor                    Params: (<game_object>)
* npc_on_weapon_strapped                   Params: (<game_object>,<game_object>)
* npc_on_weapon_unstrapped                 Params: (<game_object>,<game_object>)
* npc_on_weapon_drop                       Params: (<game_object>,<game_object>)
* npc_on_hear_callback                     Params: (<game_object>,<number>,<?>,<number>,<number>,<vector>)
* npc_on_get_all_from_corpse               Params: (<game_object>,<game_object>,<game_object>,<boolean>)
* npc_on_eval_danger                       Params: (<game_object>,<table>)
* anomaly_on_before_activate               Params: (<game_object>,<game_object>)

Mutants :
* monster_on_update                        Params: (<game_object>,<table>)
* monster_on_before_hit                    Params: (<game_object>,<SHit>,<number>,<table>)
* monster_on_hit_callback                  Params: (<game_object>,<number>,<vector>,<game_object>,<number>)
* monster_on_net_spawn                     Params: (<game_object>,<server_object>)
* monster_on_net_destroy                   Params: (<game_object>)
* monster_on_death_callback                Params: (<game_object>,<game_object>)
* monster_on_actor_use_callback            Params: (<game_object>,<game_object>)
* monster_on_loot_init                     Params: (<game_object>,<table>)
* burer_on_before_weapon_drop              Params: (<game_object>,<game_object>)

Physical objects :
* physic_object_on_hit_callback            Params: (<game_object>,<number>,<vector>,<game_object>,<number>)
* physic_object_on_use_callback            Params: (<game_object>,<game_object>)

Vehicles :
* heli_on_hit_callback                     Params: (<game_object>,<number>,<nil>,<game_object>,<nil>)
* vehicle_on_death_callback                Params: (<number>)

Squads :
* squad_on_npc_creation                    Params: (<server_object>,<server_object>,<server_object>)
* squad_on_enter_smart                     Params: (<server_object>,<server_object>)
* squad_on_leave_smart                     Params: (<server_object>,<server_object>)
* squad_on_npc_death                       Params: (<server_object>,<server_object>,<server_object>)
* squad_on_update                          Params: (<server_object>)
* squad_on_first_update                    Params: (<server_object>)
* squad_on_add_npc                         Params: (<server_object>,<server_object>,<string>,<vector>,<number>,<number>)

WARNING!
the following 2 callbacks will ALWAYS fire on level change/loaded save because the old data isn't saved for compatibility purpose
it's up to the user to check for the case in which old level name/old game vertex is nil in their code if they want to use this

* squad_on_after_game_vertex_change        Params: (<server_object>,<number>,<number>,<boolean>)
* squad_on_after_level_change              Params: (<server_object>,<string>,<string>)

Smart terrains :
* smart_terrain_on_update                  Params: (<server_object>)
* on_try_respawn                           Params: (<server_object>,<table>)

Server objects :
* server_entity_on_register                Params: (<server_object>,<string>)
* server_entity_on_unregister              Params: (<server_object>,<string>)
* fill_start_position                      Params: ()
* se_stalker_on_spawn                      Params: (<server_object>)
* se_actor_on_STATE_Write                  Params: (<server_object>)
* se_actor_on_STATE_Read                   Params: (<server_object>)

GUI :
* ActorMenu_on_before_init_mode            Params: (<string>,<table>,<game_object>)
* ActorMenu_on_mode_changed                Params: (<number>,<number>)
* ActorMenu_on_item_drag_drop              Params: (<game_object>,<game_object>,<number>,<number>)
* ActorMenu_on_item_focus_receive          Params: (<game_object>)
* ActorMenu_on_item_focus_lost             Params: (<game_object>)
* ActorMenu_on_item_before_move            Params: (<table>,<number>,<game_object>,<string>,,<number>)
* ActorMenu_on_item_after_move             Params: (<number>,<game_object>,<string>,,<number>)
* ActorMenu_on_trade_started               Params: ()
* ActorMenu_on_trade_closed                Params: ()

* GUI_on_show                              Params: (<string>,<string>)
* GUI_on_hide                              Params: (<string>,<string>)

* map_spot_menu_add_property               Params: (<CUIWindow>,<number>,<string>,<string>)
* map_spot_menu_property_clicked           Params: (<CUIWindow>,<number>,<string>,<string>)

* main_menu_on_keyboard                    Params: (<number>,<number>,<CUIScriptWnd>,<boolean>)
* main_menu_on_init                        Params: (<CUIScriptWnd>)
* main_menu_on_quit                        Params: (<CUIScriptWnd>)

* on_screen_resolution_changed             Params: ()

Technical :
* on_game_load                             Params: (<binder>)
* on_key_press                             Params: (<number>)
* on_key_release                           Params: (<number>)
* on_key_hold                              Params: (<number>)
* on_before_key_press                      Params: (<number>,<number>,<boolean>,<table>)
* on_option_change                         Params: ()
* on_localization_change                   Params: ()
* on_console_execute                       Params: (<string>,<string>,<string>,...)
* on_before_save_input                     Params: (<number>,<number>,<table>)
* on_before_load_input                     Params: (<number>,<number>,<table>)

Files :
* save_state                               Params: (<table>)
* load_state                               Params: (<table>)
* on_pstor_save_all                        Params: (<game_object>,<?>)
* on_pstor_load_all                        Params: (<game_object>,<?>)

Others :
* on_enemy_eval                            Params: (<game_object>,<game_object>,<table>)
* on_before_surge                          Params: (<table>)
* on_before_psi_storm                      Params: (<table>)
* on_get_item_cost                         Params: look at bottom of utils_item.script for details

Time Events

Written by @nltp_ashes

I. INTRODUCTION

Time events are a mechanism that exist to run a function after a given number of seconds. Before we even start, here are two important things you need to know :

1. Time events do not persist through saves : if you start a 60 seconds time event, save/load before the time event runs, the function will never be executed;
2. When a time event fires (aka, its delay is reached), the function associated with it will be executed indefinitely at each update until the function returns true.

II. CREATING A TIME EVENT

To create a time event, use the CreateTimeEvent function. It takes four arguments :

• event_id
  A unique identifier of your choice (could be your name, or something related to what is happening).

• action_id
  A second unique identifier of your choice (what matters is that two time events should not have the same event_id & action_id pair).

• delay
  The time to wait (in seconds) before running the function.

• function
  The function to execute when the delay has passed.

With all that, you can for example create three time events that will execute three different functions with a 5 seconds gap.

CreateTimeEvent("modding_book_event", "delay_func_a", 5, func_a)
CreateTimeEvent("modding_book_event", "delay_func_b", 10, func_b)
CreateTimeEvent("modding_book_event", "delay_func_c", 15, func_c)

Note that there exist two ways to pass information to a function within a time event.

First, you can pass information through the closure. It works, but you should only do it for non-userdata types. Passing userdata (alife_objects, game_objects, vectors, etc) exposes you to pure virtual function calls if the object was destroyed by the engine while the time event was pending.

local my_var = 5
CreateTimeEvent("modding_book_event", "delay_func", 5, function()
    printf("My var is %s", my_var)
    return true
end)

Another way to do it is to pass arguments through the time event function. You can give an indefinite amount of them. Each argument that you give to CreateTimeEvent will be transited to the function you passed.

local my_var_a = 5
local my_var_b = 10
CreateTimeEvent("modding_book_event", "delay_func", 5, function(some_var_a, some_var_b)
    printf("My var A is %s and B is %s", some_var_a, some_var_b)
    return true
end, my_var_a, my_var_b)

If you are having troubles reading the previous bit of code, note that it is equivalent to the following one.

function my_func(some_var_a, some_var_b)
    printf("My var A is %s and B is %s", some_var_a, some_var_b)
    return true
end

local my_var_a = 5
local my_var_b = 10
CreateTimeEvent("modding_book_event", "delay_func", 5, my_func, my_var_a, my_var_b)

A frequent use case of time events is waiting for a game_object to come online after an alife_object hs been created.

local se_obj = alife_create("my_sec", pos, gvid, lvid)
CreateTimeEvent("wait_for_spawn", se_obj.id, 0, function(id) -- 0 as a delay means it'll be ran on the next frame
  if level.get_object_by_id(id) then
    -- do something
    return true  -- if the object has spawned, kill the time event
  else
    return false -- if not, we'll run it again next frame
  end
end, se_obj.id)

III. RESETTING A TIME EVENT

It is possible to reset the delay after a time event has been created. For this purpose, use the ResetTimeEvent function. It takes three arguments :

• event_id
  A unique identifier of your choice (similarly to CreateTimeEvent).

• action_id
  A second unique identifier of your choice (similarly to CreateTimeEvent).

• delay
  The new time to wait (in seconds) before running the function (starting from the moment ResetTimeEvent is called).

CreateTimeEvent("modding_book_event", "delay_func", 10, some_func)
-- after 5 sec
ResetTimeEvent("modding_book_event", "delay_func", 10)
-- time event will end up running after 15 seconds

IV. REMOVING A TIME EVENT

Lastly, it is possible to remove a time event with the help of the RemoveTimeEvent function. There isn't a lot to say about this one, its name says it all. It takes two arguments :

• event_id
  A unique identifier of your choice (similarly to CreateTimeEvent).

• action_id
  A second unique identifier of your choice (similarly to CreateTimeEvent).

RemoveTimeEvent("modding_book_event", "delay_func")

Server and game objects

Computers are stupid! But so are we, so it's actually okay.

So, in short, we don't want our single-threaded XRay Engine to implode...

That's why we have server objects and game objects! A-Life is inherently complex and has up to 65535 objects in the game, each having a ton of computations. We kinda don't want a ton of computations, so we only compute interesting things around player and everything else is simplified.

Server objects

All objects in the game have two faces: server and level objects. Server object exists always, and has all the really basic stuff about the object: what it is, its coordinates, its parent object and some more basic info. Server objects are also called offline objects, but mainly just server objects.

You can get a server object for something in the game using alife():object(id). Because the engine functions are Really Fucking Fragile we also have a function in _G called alife_object which does the same, but also checks that your id is what everyone expects it to be (a number). Better use it, mostly no overhead.

Special case: id of player (or actor) is 0, and player server object can be obtained with alife():object(0).

Level objects

Unsurprisingly, there also are online objects, or game objects, or level objects. Interesting parts about them: they only exist around player and they have more functionality than server objects. Online radius setting defines what exactly is "around".

You can get a level object for something using level.object_by_id(id). All the level objects are also saved in db.storage table, which is pure lua and won't randomly break. As with server objects, we have a function in _G called get_object_by_id which will perform a sanity check and give you the object either from db.storage or from level.object_by_id. Use it, it's good.

Special case: level object of actor is always online and is saved in db.actor.

:3

Scripted animations

Theory

The first thing to know is that animations can be divided into a few categories:

Motions

• They represent actual hands, NPCs or actor movements
• Stored in .omf files
• Unique to an object

In this article we’ll focus on hands animations which are, for example, sprinting or weapons reloading. FDDA items animations are also motions. Motions are usually unique to a specific object. For example, AK74 reload animation will only look nice when used with AK74 or any other gun that is set up for this specific motion. That means you can still play it in your script with empty hands, but if you play it while holding a PKM the machine gun won’t play any reload animation at all.

Why so many details, you may wonder? Point is, a motion can have interesting use cases. For example, you can play a pistol holstering animation to temporarily hide one or both hands. Or you can use it for gestures as well as other unarmed animations, items animations - there's quite enough room for creativity.

Also, an .omf file itself is not a motion. .omf files usually store multiple motions. If you want to add a new motion, you’ll need to either

1. put your motion into an existing .omf file or
2. make a new .omf file that will store your motions.

.anm animations

In turn, these can be divided into two subcategories:

Camera animations

These are much simpler due to their nature. Camera animations represent a screen effect - for example, leaning when an actor equips a helmet or a suit, ‘kickback’ effect when enhanced recoil effects are enabled, camera animations when reloading (mostly used by weapon mods like Boomsticks and Sharpsticks; not to be confused with hands motions) etc.

‘Universal’ animations

This is not an official name, of course, it’s just something I came up with to distinguish these from the simple screen effects. They're also called 'Blend animations' in engine. I’d better describe them with an example.

In Anomaly, there’s a ‘misfire’ animation. Try to shoot a gun without any ammo, and you’ll see slight hands movement. This is ‘misfire.anm’ animation.

Point is, this is not exactly a screen effect type of .anm file, and yet this is not an .omf-type motion. It can be used with any object the actor is holding, i.e. it’s not tied to a specific gun.

So technically, these are both .anm files. I just decided there needs to be some sort of distinction. As of now this documentation focuses on playing 'blend' animations.

.anm are separate files unlike motions from .omf files, and every single .anm file can be just placed into anims/ folder in gamedata and used directly.

.ppe effects

These are camera animations with more possibilities: besides camera movements, they can also include, for example, duality effect (when drinking vodka or when there was an explosion next to the actor), grain effect in radiation zones etc. Vanilla night vision is also a .ppe effect.

.ppe files work similarly to .anm files - they’re separate and go to anims/ folder as well.

Practice

Now let’s have a look at what we need to play animations in scripts.

Motions

To play a motion, we need a few components:

1. An .ltx file containing the basic parameters of the motion we’re going to use.
2. A script function to play it.

Setting up motion parameters

1. Create a config .ltx file in configs/items/items and give it any name, but make sure it starts with items_. Example: items_my_anims.ltx.
2. Set the parameters. We’ll examine them by looking at this example.

[anim_my_sec]

    hands_position              = 0.033, -0.155, 0.1

    hands_orientation           = 0, 0, 0

    hands_position_16x9         = 0.033, -0.155, 0.1

    hands_orientation_16x9      = 0, 0, 0

    anm_my_anim                 = name_of_motion_that_will_be_played

[anim_my_sec] is an animation section name. It’ll be used in the script.

hands_position, hands_orientation, hands_position_16x9 and hands_orientation_16x9 are hands position/orientation parameters. They work similarly to weapon position parameters.

anm_my_anim is a motion name. From what I saw, it should always be started with anm_ in such a config. Not to be confused with an .omf file name. For example, if your .omf file is called my_new_file.omf and it stores a motion called my_motion_1, specify my_motion_1 here.

To make a test placeholder, you can also open any weapon config file and choose any of the motions specified there (like, anm_ak74_reload, anm_svd_sprint etc.)

Script function

The function that lets you play a motion is:

game.play_hud_motion(hands, anim_section_name, motion_name, bMixIn, speed)

Now let’s have a closer look at its arguments.

1. (int) hands
   • Specifies what hands will be used to play an animation. 1 - left hand only, 0 - right hand only, 2 - both hands.
   • Note that it's not possible to play a left-handed (like detector draw) animation for the right hand. But you still can play any two-handed animation with only one of the hands.
2. (string) anim_section_name
   • This is the name of the animation section specified in the config file.
   • In our example this is [anim_my_sec].
3. (string) motion_name
   • This is the name of the motion within the specified section in the config file.
   • In our example this is anm_my_anim.
4. (bool) bMixIn
   • This one is a bit unclear - it’s missing from lua_help.script, and I’m not sure if I understood how it works correctly. This is how this argument is named in the engine, probably it has something to do with mixing or transition from one motion to another.
5. (float) speed
   • Sets the playback speed of an animation. Example: 0.5, 1.2, 5.5 etc.

Supplementary functions

game.hud_motion_allowed()

Checks if a hands motion can be played at the moment. Useful as an additional safety check. Returns True or False.

game.get_motion_length(anim_section_name, motion_name, speed)

Gets the specified motion length. The parameters are identical to those in play_hud_motion. Note that it returns time in milliseconds, so in order to get the actual length you’ll need to divide the result by 1000. Useful to know when the motion is over.

game.stop_hud_motion()

It will stop any hands motion that is currently playing (since it can’t accept a specific motion as an argument), not only the one you’re playing in your script. Example: you have an animation from FDDA that is currently being played. This function is called from your script, intentionally or not. It will stop the current FDDA animation as well, despite the fact that it wasn't called from any of the FDDA scripts.

Things to consider

1. It’s safer to always stop the looped animations explicitly. This can be done by:
   1. playing a non-looped and non-restart animation - the previous one will be stopped.
   2. calling game.stop_hud_motion().
2. Consider adding more protection from breaking something.
   1. Know when to stop an animation and how not to make it looped when it’s not wanted. Remember to check the necessary conditions to make sure it makes sense to play it at all at the current moment.
   2. Know the callbacks you’re using to play animations. This may affect the animation behavior. Incorrect callback usage may lead to unwanted results, softlocks or sometimes even crashes.
   3. Call game.only_allow_movekeys(true) if you don’t want the user to break an animation by pressing any action keys (like item quick use), and then restore the controls with game.only_allow_movekeys(false).
   4. hide_hud_inventory() and db.actor:activate_slot(0) can be used to close the backpack inventory or force hide an active weapon if needed. Detectors can be manipulated in a similar way with:

    local det = db.actor:active_detector() or nil
    det:switch_state(2)

and then restored with:

    det:switch_state(1)

.anm animations

It’s simpler to play these. Here we don’t need any configs. The files are played directly. The function is game.play_hud_anm(path, hands, speed, power, looped, restart).

In this case I assume the played animation is “misfire.anm” mentioned earlier - I used this function for it in my addon. You can try it with different animations.

The arguments are:

1. (string) path
   • Path to the .anm file.
   • It is predefined that a file is in the gamedata/anims folder. That being said, the path should look like this, for example: "camera_effects\\actor_move\\strafe_left.anm".
   • The real path in this case is gamedata/anims/camera_effects/actor_move/strafe_left.anm.
   • If the file is in the root anims/ folder, just specify the file name.
2. (int) hands
   • Specifies what hands will be used to play an animation. 1 - left hand only, 0 - right hand only, 2 - both hands.
3. (float) speed
   • Sets the playback speed of an animation. Example: 0.5, 1.2, 5.5 etc.
4. (float) power
   • Sets the ‘amplitude’ of an animation. The more it is, the more noticeable the animation will be. When set too low, it may be too ‘faint’. Example: 0.51, 1.65, 5.1 etc.
5. (bool) looped
   • Defines if an animation will loop until stopped by any means. Can be True or False.
6. (bool) restart
   • Specified whether or not an animation can be restarted after it was finished, or it should only play once. Can be True or False.

Supplementary functions

game.stop_hud_anm(path, force

Stops a specific .anm from playing. path is identical to the one above. force is a boolean parameter which makes it possible to force stop it - a bit more ‘harsh’ method.

game.stop_all_hud_anms(boolean)

Stops all .anm’s that are currently played.

game.set_hud_anm_time(path, time)

This function alters the playback speed of the specified .anm file. path is still the same as it was mentioned earlier, and time is actually a speed value (float).

The name may be a bit confusing, but judjing by the engine code it actually manipulates the .anm speed:

float speed = (anm->anm->anim_param().max_t - anm->anm->anim_param().t_current) / time;

And a descriptive example in actor_effects.script:

game.play_hud_motion(1, mc_anm_sec, "anm_hide_hand", true, hide_hand_speed)
new_speed = game.set_hud_anm_time(anm_name, ((mc_anm_time_1 + mc_anm_time_2) / 1000) + anm_additional_length)

Things to consider

1. Unlike motions, .anm’s can be stopped directly by calling game.stop_hud_anm. It makes it possible to stop a specific .anm only.
2. .anm’s can be ‘layered’ - i.e. it’s possible to play two or more .anm files at the same time. This can provide interesting and good-looking results.
3. However, it may be tricky to play a few .anm’s with the same name at the same time because the function relies on the file name (which is already played in this case). If you want to play the same effect but with different parameters, consider making a copy of the .anm you use, give it another name and play them with two functions with different arguments according to the desired result.
4. In practice, .anm playing parameters often require fine-tuning by testing it in-game. The same set of parameters for different .anm's may often lead to substantially different results. Achieving a good looking result may require patience.
5. Though .anm's usually can't cause a softlock or break something substantially, it's still advised to stick to the safety recommendations described in the 'Motions' section.

.ppe effects

These are the functions for them:

1. level.add_pp_effector(path,id,looped)
2. level.set_pp_effector_factor(id,power)
3. level.remove_pp_effector(id)

The first one is used to start a .ppe effect. Arguments:

1. (string) path
   • It works absolutely the same way the path argument from game.play_hud_anm does.
2. (int) id
   • An ID of the effect. Can be any number.
   • Used for removal of the effect later on.
3. (bool) looped
   • Defines if the effect will loop until stopped by any means. Can be True or False.

The second one is used to alter an already existing effect added by add_pp_effector. Arguments:

1. (int) id
   • The ID of the previously created effect.
2. (float) power
   • Effect intensity factor from 0 to 1.

The third one stops and removes the added effect. The only argument is id - use the same one you specified when adding the effect with add_pp_effector.

Creating and setting up a model in Blender

This article is about creating a model and setting its parameters

Beginning

• First, familiarize yourself with the limitations and capabilities of the format .object (because you may export to it more often than to .ogf) to avoid errors.
• This article will talk about textures, read an article about creating and preparing them.

Start

Create or download the model you like. Do a UV if you don't have one.

• Example

The model itself:

UV:

Texturing

Textures can be created in any program designed for this purpose, or you can simply download them.

Texture:

Important note about texture maps

In STALKER, due to its outdated engine, only the following texture maps are used:

• Color Map (.dds)
• Normal Maps (For Stalker they are used as .bump and .bump#) (The Blender X-Ray addon does not support the .bump format at this time (June 2022).)

So extra texture maps will have to be removed.

Here you need to add your created texture in .dds format

As a result, in the Shader Editor () our textures should look something like this:

So after creating the model, the UV and the texture, the setup within Blender begins.

Setting up

• Model

First, the model itself will be set up. You can start by positioning the model over the origin in this way (The "Drop It" addon for Blender is highly recommended for such actions):

Then apply the coordinates with Ctrl + A > All Transform. This will allow us (if you make for example a model library or work in the SDK) to drag and drop the model on the surface.

Next, we need to adjust our model to normal size (so that in the game it will not be big or small). If you have already set up the addon to use and set up the necessary paths to your folders, you need to import into the scene model of some person from the game.

In the N-panel there should be a tab "X-Ray" in it unfolds the list "Viewer" and we click "Open Folder" ().

The Blender explorer window opens. Go to our unpacked folder with the game files (namely the folder "meshes"). The character models you need are in the "actors" folder, where the faction models are sorted into folders. (More about the structure of folders, main folders and files you can learn here)

Select the desired folder with the models and click on the "Open Folder" button.

Depending on the size of the models in the "Viewer" folder may take longer to open than you would like. So, "Viewer" is open. It shows all the models in the selected folder. Click on any model and a character model appears in front of us.

Next, we just adjust our model to acceptable proportions. After fitting, apply transformations to our object.

In the "Viewer" list, we can click on "Close Folder ()" to close the list of models and the model imported to us in the scene, too.

Creating a dynamic model

At this point we have to decide what type of model we want to use (static, dynamic, or something else). (About the types of objects you can learn here)

It was decided to make our object dynamic. To do this, you need to create a bone and a vertex group (so that the bone can affect exactly the vertices you choose). Select the model and go to the "Object Data Properties" () tab Image here

Under "Vertex Groups" click on the plus sign (a "Vertex Group" with the name "Group" () will be added) and double-click to rename it (the same name will be needed later for the bone).

The next step is to create a bone (Shift + A > Armature > Single Bone).

To make our model move like the bone in the future, we need to rename the bone to the name that was given to "Vertex Groups" ().

And rename the bone.

Select our object and switch to "Wireframe" mode () ("Z" Button) (this is optional). Place the bone approximately in the center of the model.

After that, apply the bone transformations (Ctrl + A > All Transform).

Select our model and go to the "Modifier Properties" () tab.

In the "Modifier Properties" () tab, add the "Armature" modifier () (Add Modifier > Armature (under Deform)).

The modifier has the following necessary items:

• Object ()
• Bind to () Vertex Groups

In the "Object" () field, select our bone (you can select it with the pipette ()). Also make sure that the checkbox next to "Vertex Groups" () is marked. These actions allowed us to bond our object and bone, but not yet to the fullest extent.

Next step: First select the bone after selecting the model, press Ctrl + P. A list appears, select "Bone" (or other settings, because sometimes selecting "Bone" may not help).

This allowed the bone and the model to be fully bonded together. Now when the bone moves or rotates, the model will move with it.

Now you have to set the bone properties for X-Ray.

Bone

Select the bone and go to the "Bone Properties" () tab.

We see the "X-Ray Engine: Bone" section.

The desired field is "Shape Type" (where you choose the type of shape (for collision)). From the whole list, our object is more suitable for the "Box" type. Let's choose it. Next, click the "Edit Shape" button to check and edit the Shape itself. The Shape of the bone appears and it does not match the model. The Shape that just appeared is automatically selected and the "Object Properties" () tab is selected.

In the same tab we see the "X-Ray Engine: Edit Helper" section with three buttons:

• Apply Shape (accepts changes to the bone shape)
• Fit Shape (Blender will automatically try to fit the Shape to the size of the object)
• Cancel (closes Shape editing mode)

Apply Shape may help in some cases, but not in this one (nothing happens after clicking), so you need to adjust the Shape manually. Without going into Edit mode, press "S" and start fitting the Shape to the model. Going through the combinations, changing the shape of the Shape, we finally create an acceptable Shape.

Accept the transformation by clicking on "Apply Shape" (). Everything will apply and the Shape will disappear. To check the correctness of the shape and adjust the center of mass for the bone, go to the "Object Data Properties" () panel.

Here we see the "X-Ray Engine: Skeleton" section and the two buttons we need:

• Display Bone Shape
• Display Bone Mass Centers

Click on "Display Bone Shape" to check the bone shape

And by clicking on "Display Bone Mass Centers" a Cross will appear, from which you can understand where the center of mass is located (its mass and location can be edited in the tab "Bone Properties").

Go to the "Object Properties" () tab. Here you will find the "X-Ray Engine: Object" section.

Remember that our object, by design, will be dynamic, so click on the button "Object", where we select the type "Dynamic".

The editing of the bone parameters is finished, the next step is Materials.

• Material

Select our object and go to the "Material Properties" () tab.

Here we see the name of our material and a list of "X-Ray Engine: Material" with lots of items.

There is no point in telling about each point here. (there is a separate section in the book)

The items we need for the model now are:

• Shader (This setting is responsible for the appearance of the surface.)
• Compile (Here are descriptions of the settings that the level geometry compiler uses)
• Material (Here you can select surface materials)

Select the shaders you want.

Well, the model setup in Blender is done. Congratulations!

The final stage

• Checking the model for correct operation

To check the model you can go the following ways:

• Load the model into the SDK and check
• Export the model in .ogf format and add it directly to the game.
• Check the model and parameters through third-party programs

Creating an animation in Blender for a HUD object

Related Videos

Creating animations for the camera in Blender

Beginning

• First, familiarize yourself with the .anm file format.

Creating animations

Create or enter a Blender scene.

In the N-panel in the X-Ray panel in the Add rollout, click on the "Add X-Ray Camera"() button.

Choose a empty and animate it!

Export

To export the animation you need to select the empty through the export operator in .anm and export

Editing existing animations

You want to edit existing animations of a weapon or other item? You're insane.

Begining

Before you begin, familiarize yourself with the animation files:

• skeleton animations (.skl, .skls, .omf)
• camera animations (.anm)

Editing hud animations

1. import a hand hud model
2. import a model of a weapon or something else
3. import the hand and object animations you want
   1. (Optional) You attach the main bone of the object to the lead_gun bone (Using Copy Transform)
4. Edit

Editing camera animations

1. import the camera animation
2. Edit

Texturing

About:

This section will deal with the creation of textures, their preparation and formalities

Creating and preparing textures

Related Videos

Beginning (Via Paint.net)

First, familiarize yourself with the supported texture compression (.dds .bump .bump#)

Start

First we have to create a texture, or we have to download one. Next, we need to convert our texture into .dds format. To do this, you can use any program of yours that can do such a thing. (or you can take a program from this list)

The most commonly used program for this is Paint.net. We download the texture and save it as .dds. The Save Settings window appears.

We have to choose the texture compression that suits us.

Save our texture. All of this may come in handy, for example for creating a model.

Working correctly with icon atlases

Greetings, this is comrade Hrusteckiy - UI-programmer, whose work can be seen in the New Project, Last Fallout Overhaul, Oblivion, Hike, and many others, also made 100x100 icons for the original game. Noticed that many modders suffer from improper saving textures and work with them. This guide will make their life easier and teach them to do without mistakes (by the way, came to this myself through their own messes).

Let's start with software

• First of all, use Photoshop CS5/CS6 or CC (I use 2019)
• Second, forget about the Stalker Icon Editor
• Third, we need Paint.net. That is, we use only two programs to work with the icons themselves, not counting the program for rendering them

Next, you need to work with the source - .tga ideal buffer format for these two programs, save it in 32-bit format.

To add new icons, use Paint.net. We make a new layer, paste on it the picture we need and adjust to the size (bilinear method), select the area, cut and paste to the main layer, thereby erasing the previous icon, if any. We save and go to Photoshop. Here we turn on the grid (Ctrl+'), its size is adjusted here, by default it is 50 pixels.

IMPORTANT!!! DO NOT USE THE RIGHTMOST AND BOTTOMMOST CELLS, THEY ARE NOT WHOLE AND ARE SMALLER THAN THE REST BY A FEW PIXELS.

We select with shift color+alpha, and, if necessary, adjust the icon within a cell, save it. To copy icons from one atlas to another, select the icon on one, copy and paste on the other - it's best to do it with the color and alpha selected, so you don't have to transfer separately. Next, we go to "layers" and unlock the layer - this opens us information in the properties about the selected element and its position. This is where we will find out the coordinates, for 50x50 we have to use a calculator, and for 100x100 we just cut off two zeros each.

UPD: in CS5/CS6 you can get coordinates on F8 (in the new versions have simplified access and it is on the properties fold).

Here is the position of the X - 950, divide by 50 and we get 19 - this is the number written in inv_grid_x. Similar story with the player. W - Width 50, divide by 50, we get inv_grid_width equal to one. It's the same with height.

AFTER UNLOCKING THE LAYER, DON'T SAVE THE ATLAS, JUST CLOSE IT!

Open the atlas in Paint.net or in Photoshop (you need the .dds plugin).

To save in Photoshop

To save in Paint.net

Sources

Ap-pro Topic

Hrust Contacts

• VK
• AMK
• Ap-Pro
• Discord - Hrust#8964

Mapping

In short: Don't work with maps. You can compile and run new maps in the game, but it is not a pleasant experience in any way. You cannot change existing maps. Anomaly devs are working hard to fix this, and we expect the situation to get better with Anomaly 1.6.

But, if you really are adventurous:

To compile, you need to make a location build. To do this, open or create a location in the Level Editor in the SDK.

For location build this is the minimum set:

• 1 light source
• 1 spawn element
• 1 glow

If the location will have stalkers, you need to create ai grid

Location building

Created a folder with the name, which was specified in the scene properties. It contains all the data about the location.

Compiling the location

In order to compile a location, you need to put it in the:

• game_maps_single.ltx
• game_levels.ltx

After that you can use compilers that are included directly in SDK, or use third party compilers (such as Universal x64 level compilers).

Creating a location in Blender

Beginning

• download the SDK (A list of SDKs can be found here)
• Familiarize yourself with the formats for levels (.lights, level, .ai, .cform, .details, .env_mod, .fog_vol, .game, .geom, .geomx, .hom, .ltx, .ps_static, .spawn, .wallmarks, .som (List here))

At the moment in the addon for Blender it is not possible to create a full-fledged location (no compiler, creating ai-nodes, etc.), so you need to use it with the SDK.

Creating Level

Simply create a level. To do this, you can use, for example, Stalker Asset Library (all objects from the trilogy).

Then you can assign certain flags to objects, such as

• Sectors
• Portals
• HOM
• SOM

And so on.

Those objects that were created by yourself need to be exported in .obj format to the object folder in your SDK and put export path to that file in the model properties.

Next you need to export the scene in the format .level

Next, you need to build and compile the location

Multimaterial Terrain Guide

Written by the New Project mod team

• VK
• AP-PRO
• ModDB
• Telegram
• Discord

So first, let's try to understand how the rendering system works in general

A terrain is a regular 3d model consisting of many polygons. They can have different materials that will determine the type of their surface: grass, earth, asphalt, etc. In the X-Ray engine, a material has two important parameters that determine its type:

• Game Mlt - actually the material itself, which determines the sounds of footsteps on the given surface, bullet hits, etc.
• Shader – determines the appearance of this material

Terrane settings in SDK Actor Editor

Also, a terrane has a texture, but it defines nothing more than its color in the game - it doesn't even have a bump. And, of course, this texture is common for all the materials in a given terrane. So there is no sense to dwell on it for a long time. Also in our analysis we will skip the Compile parameter.

The material, texture and shader of the terrane can be changed in both SDK Actor Editor and SDK Level Editor in the Library Editor tab. Or even in Blender itself, whichever is more convenient for you.

Let's talk more about the material shader. As already mentioned, it is responsible for the appearance of the material, namely, it defines its detail-texture. No, not the one we wrote about above. Detail-texture is responsible for the pattern of the material - grass, sand, pebbles, etc. This texture has a bump and it is around these textures that we are talking about today.

Customization of shaders and their detail-textures is done in SDK Shader Editor. Opening any terrane shader in it (so-called level-shaders) we will see that all of them have... Wait, why do they need 4 textures? Which of them will be displayed in the game?

RGBA channels of one of the level shaders

To understand this, let's take a close look at these textures. Each of them is assigned in some one of the channels - R (red), G (green), B (blue) or A (alpha). You have already guessed that these are the channels of the RGBA color model, namely - the channels of the terrane mask, with the help of which the game engine understands which texture of a given shader should be shown in the game. Let's look into this in more detail.

The terrane mask uses only four colors - red, green, blue and black - the very same RGBA channels. How does it all work? Let's try to explain it on the example of how the game engine understands it:

1. the game sees the terrane with all its many polygons
2. From each polygon it reads its material and shader
3. In the shaders the game sees the same 4 textures.
4. Next, the game reads the mask of the terrane and the color of each polygon
5. And finally, the game, according to the color of the mask of a particular polygon, selects from its shader the texture that corresponds to the color channel of the mask.

For example, the game sees a polygon with the material "grass". At the same time, the game sees that this polygon is painted with a green color mask. Based on this, the game decides that in the shader of this material it should take a texture from the G channel. Of course, in a properly configured shader, the grass texture we want should be assigned to this channel. Same with the red, blue and black colors of the mask.

Green grass meets red earth (Blender)

The same stretch of terrane in the game

The principle of shader operation seems to be clear. But why do you need other texture channels in the shader, if only one is used for rendering? They are responsible for smooth transition of this material to other ones. We decided for ourselves that channel G on our mask is grass, channel R is earth, channel B is asphalt, and channel A is sometimes sand, sometimes something else. In fact, we could do it the other way around - give R to grass, B to earth, etc. But it doesn't matter at all, because we decide in the shader settings what texture to feed through what color.

So, let's assume that our green grass polygons met with red earth polygons. You have already guessed about the ground material, that in the R-channel of its shader the ground texture must be assigned - it is this texture that will be rendered. What do we need to do to make a smooth transition between the ground and the grass? The obvious solution comes to mind - to make a smooth transition between red and green on the mask, i.e. just blur the boundary between the colors. However, this will do nothing, there will be no smooth transition in the game anyway. The engine has another mechanism for that.

Example of properly configured channels for transition

Let's remember the unused channels in shaders. For grass, the G channel is responsible for texture rendering - RBAs remain free. For the ground, the R channel is responsible for rendering the texture - GBAs remain free. In order to make a smooth transition between grass and earth, you need to do a very simple action - in the grass in channel R to assign the texture of the earth, and in the earth in channel G - the texture of grass. And indeed, if polygons of green grass meet polygons of red earth, the grass begins to change to the texture that is assigned to it in the channel R, and the earth begins to change the texture to the texture that is assigned to it in the channel G. As a result, both grass and earth from their sides generate a smooth transition to the neighboring material, and at the junction of these materials you can't see a seam (unless, of course, we made a mistake and assigned the same textures in the corresponding shader channels).

The ground in channel G was mistakenly labeled gravel

All this is difficult to understand from the first time, but try. You can clearly see the principle of smooth transition generation if you assign wrong textures to shaders. For example, let's try to assign sand to the grass in channel R and gravel to the ground in channel G. In the game it will look like this: in the place where the transition of grass to earth should have taken place, a smooth transition of grass to sand will be generated on the grass side, and on the earth side - the transition of earth to pebbles. And at the junction of sand and pebbles, logically, there would be a visible seam. On the one hand, because the textures are not the same, and on the other hand - because the generation of a smooth transition has already occurred earlier.

The ground in channel G was mistakenly labeled gravel

As you have already guessed, the same is true for combining channel B with channel G, channel A with channel R, etc. In any combinations, one thing is important - all shaders must have the same detail-textures in their respective channels. The only difference is that for one shader, for example, our earth, channel R will be responsible for rendering a texture, and for others - for transitioning to this texture. The same is true for the other G, B and A channels.

Thus we conclude that there are no unnecessary mask channels in the shader, all of them are used either in rendering or in transition generation. Of course, we should not forget that all declared detail-textures must have bump, bump# and thm for correct display.

And now we're ready to understand why the X-Ray engine allows you to assign only 4 materials to a terrane - because one material can only smoothly transition into 3 other materials. After all, if the grass is rendered through the G channel, it can only transition to the the remaining RBA channels - there are no others. And if we could set the color of the mask through which the detail-texture will be rendered (for example, yellow or blue), then we could use more materials and create more combinations of them with each other. But in the classic version we are limited to only four mask channels and, accordingly, four terrane materials. And these are already, apparently, limitations independent of the engine. And in general, this is a story from a parallel universe....

Now let's try to understand how we can "legally" bypass this limitation. To understand the text below you must understand exactly how the standard terrane rendering system works and how terrane shaders are organized.

Scheme 1. The most complex in this document

Take a look at scheme 1. We see the familiar grass (green), earth (red) and asphalt (blue). All of these materials, as we know, can be combined with each other in any form. Notice the red square inside the blue square. What kind of material is that? In the standard scheme of building terrane shaders, it should be a ground, because we have agreed that all terrane shaders must have a ground in the red channel, otherwise the generation of a smooth transition between materials will be disturbed. But there is one important trick in this scheme - the left red square does not intersect with the blue square, nor with the second red square. Now strain yourself, it's going to be tricky.

The grass in channel R is tuned to ground, and in channel B to asphalt, so it can generate a smooth transition to the left red square and right blue square. It's business as usual, it seems like nothing special. But if the blue square (asphalt) does not intersect with the left red square (ground) - are we obliged to assign a ground to its R channel? In the standard scheme, yes, because they will intersect somewhere. They will, won't they...?

What if, on our terrane, asphalt never actually intersects with earth, what does that give us? It allows us to free up the R channel from the asphalt and set it up to work with some other material that just like the ground will be fed through the R channel. Got it?

Take another look at Scheme 1. Let the left red square be earth as usual, and the right one be sand. For everything to work, the blue square must have sand in the R channel - only then will it be able to generate a smooth transition to sand. And the sand, in turn. channel B must be set to asphalt.

Can the blue square intersect with the left red square? No, because they have different textures in the R channel, and crossing them will render the wrong transition (see example above). So if asphalt will never make contact with the ground, then we don't have to set asphalt to ground and ground to asphalt. Take a few minutes to think about what you've read. When the idea becomes more or less clear - keep reading.

Scheme 2. Slightly easier, but much more interesting

Let's complicate the task - add a new blue square inside the red square. If you have understood the new idea of shader customization, you can guess that this new blue square does not have to be asphalt - let it be, for example, gravel (see Scheme 2).

So, I hope the idea of squares is clear and now we are ready to make one important conclusion - mask channels can be used more than once in different shaders. In other words, we can have two shaders that use blue or any other channel to render their texture. The main thing is that these two shaders must not touch each other anywhere, otherwise they will not generate a proper transition between them. The other channels will still be used to generate transitions. This is the most important thing we need to understand at this point.

But even though this approach theoretically allows you to create more than 4 materials, in practice it turns out to be useless. Seriously, take another look at Scheme 2 and think, in what real situation will you have to put one material inside another like a matryoshka doll? In practice, we most often want a terrane that is 60-70% grass to have 5-6 other materials in various combinations. For example, we want to make a lake. It should be surrounded by grass with specks of earth. Then the grass together with earth should pass into sand, and sand - and bottom silt, which will already be covered with water. Alas, but the above "matryoshka doll method" will not allow to create such complex transitions. However, let's repeat what we have learned from this method - one mask channel can be used for rendering many times.

Now we'll look at a method that will really help us create an unlimited number of materials in any combinations.

First of all, let's take the most common terrain again with 4 materials, which are combined with each other in various combinations. It will be better if this is some kind of test level. Let the materials of the terrane have these shader settings:

• green - grass
• red - earth
• blue - asfalt
• alpha - sand

In such a situation, all channels of the mask are occupied, there is nowhere to go. And we want to make a gravel section on the terrane. What can we do? We have already found out that even if all the mask channels are occupied, we can reuse any of them with another material. But how do we use them when our source materials are already combined in all combinations and we don't want to disrupt them? In other words, what if, in Scheme 2, the red and blue squares do overlap with each other and their shaders are fully tuned to each other?

This is where the "fake transition method" comes to our rescue. This is the same "sorcery" that we were able to discover after months of experimenting with shaders. Now work hard, it's about to get hard again.

Just adding new material for now:

1. In the 3d editor create a new gravel material and assign it to some test polygons that are surrounded by grass.
2. In Shader Editor create a new gravel shader (gravel). In its channel R we assign gravel texture (it will be rendered), and in channel G - grass texture (with it we will make a transition). In channels B and A you can assign anything you want, we don't need them yet.
3. In the mask terrane draw a red color in place of the new test polygons of gravel
4. Assign a new shader to the new material

If we leave it like this now and put the level on compilation, we will see the following in the game. Gravel will be rendered, but at the place of its correct transition to grass it will encounter an incorrectly generated transition of grass to ground - because the ground has the channel R channel is set to ground. And at the junction of transitions we will see a clear seam. Thus we are once again convinced that it is impossible to insert new material just like that. But we will go further:

1. In 3d editor surround the gravel polygons with a "frame of polygons". Speaking professionally - extrude (extrude) the edges of the polygons of gravel outside. You should get something like a square from the scheme 2.
2. There in the 3d editor create a new material and assign it to the polygons of the frame, which now surrounds the gravel. Looking ahead, this frame will generate a smooth transition of grass to gravel, so for convenience, name the new material "grass_to_gravel".
3. In Shader Editor create another material, name it the same "grass_to_gravel". In its G channel assign grass (this is the render channel), and in its R channel assign gravel (this is the transition channel).
4. Assign the new shader to the new transition material
5. Do not do anything in the mask terrane, because if you squeezed the edges outward, they now diverge in the area of green color. And we need it, because the frame texture will be fed through the green channel.

And now if you have done everything as described above, you can compile the test level and see that you have just added a fifth working material to your terrane, which generates the transition to grass without any problems. The operation of the original 4 materials is not disturbed in any way. Impressive? Now let's take a closer look at what we've just done.

As you have already realized, the essence of witchcraft lies in the "frame" that we have created around the new material. It acts as a kind of buffer or channel settings switch, with the help of which we ourselves determine what material our grass will change into.

Note again the grass shader, in its G channel we assigned grass, and this channel according to the terrane mask is used to render the texture, and the other channels are used to generate transitions to other materials. But what if we create a shader that also has grass in its G channel and something else other than grass in the other channels? That's exactly the kind of material we just made, because the grass in the R channel has earth, and the transition has gravel.

As a result, we have two different materials, with the same texture in the render, but with different textures in the "transition" channels. At the junction of grass and frame, the original grass purely technically generates a "transition to itself", but in fact we do not see this transition in the game. Thus, the G channel of both the grass and the fake is simultaneously used for rendering and transition. And the other channels remain free, and we can use them as we want. In the case of the original grass, all channels are already occupied, but in the case of the fake transition they are free. And this is what allows us to assign any new material to it. We have chosen gravel, so we can assign gravel to any of the remaining channels (we have chosen channel R, but you can use any free channel), and then we just need to set the appropriate gravel texture in the shader of our new material.

Thus, having created a fake transition, we can place in it as in a matryoshka doll the new material we need. And such matryoshka dolls on the terrane can be as many as you want.

Quests

Introduction TO REDO

Courtesy of tdef#6225

A quest is defined by adding a section inside \configs\misc\task\task_manager.ltx or any of the files included by it.

task_manager.ltx

[mytask]
status_functor = mytask_status_f
target_functor = mytask_target_f
; there are more things but these are the essentials to have it running

The status functor is a function that gets called every few seconds while the task is active, used to progress the task logic. The target functor is used to decide where to show the quest marker while the task is active.

The status functor needs to be defined inside task_status_functor.script, while the target functor inside task_functor.script To avoid bloating those two scripts you can define those functions in a separate file.

mytask.script

function task_status_functor.mytask_status_f(tsk,task_id)
	-- your code
	-- return "fail" or "complete" to fail/complete the task
	-- change the value of tsk.stage to change the stage of the task
end

function task_functor.mytask_target_f(task_id,field,p,tsk)
	-- your code
	-- the return value must be a number or nil
	-- engine will place a task marker on the object 
    -- with the id returned by this function or delete it if nil
end

-- this below is not required, adds a "start_mytask" command
-- in debug menu to start the task 
_cmd = debug_cmd_list.command_get_list()
function _cmd.start_mytask()
	task_manager.get_task_manager():give_task('mytask')
end

Now by calling "start_mytask" in debug menu you will get a task with default task icon (the compass) and a ugly TITLE_DOESNT_EXIST title and DESCR_DOESNT_EXIST description, also nothing happens.

Title and description can be defined in two ways: static (not really, it's actually a condlist which is a can of worms, so for now pretend it's a static value) task_manager.ltx

[mytask]
status_functor 	= mytask_status_f
target_functor 	= mytask_target_f

title 	= st_mytask_title
descr 	= st_mytask_descr

With st_mytask_descr and st_mytask_title defined inside a xml file in configs/text/eng or rus/

With functors task_manager.ltx

[mytask]
status_functor 	= mytask_status_f
target_functor 	= mytask_target_f

title_functor 	= mytask_title_f
descr_functor 	= mytask_descr_f

Title and task functors must belong to task_functor namespace so you need to add.

mytask.script

function task_functor.mytask_title_f(task_id,field,p,tsk)
    -- 	title of the task will be the text returned
    --  you will have to define your strings in an xml and "translate" the string id 
    return game.translate_string('st_mytask_title')
end

function task_functor.mytask_descr_f(task_id,field,p,tsk)
    -- description of the task will be the text returned
    return game.translate_string('st_mytask_descr')
end

After doing either task should show the title and description you set.

Now you need to decide a rough outline of the task, dividing them by stage makes organizing code easier, but nothing prevents you to hangle all the logic in a single stage, however stage matters if you want the task to be part of the random tasks given by npc that will be explained later.

0. Stage 0: kill the soldiers

1. Stage 1: return to fanatic

Edit the status and target functor to spawn a soldier squad at the fallen bridge and make the task target them, and the target fanatic after the soldiers have been killed.

mytask.script

local squad_id
function task_status_functor.mytask_status_f(tsk,task_id)
    -- if it's stage 1, then we're done
	if tsk.stage > 0 then return end

    -- if it's stage 0 and it hasn't been done yet, spawn the army squad at the fallen bridge and make them stay there
    if not squad_id then
        -- spawn the squad 'army_sim_squad_novice' at the smart 'esc_smart_terrain_TODO'
        -- you can check smart terrain names with debug hud on pda map

        -- TODO: alun_utils are outdated
        local se_squad = alun_utils.create_squad('army_sim_squad_novice', 'esc_smart_terrain_TODO')
        
        -- force the squad to go and stay at the smart 'esc_smart_terrain_TODO'
        -- this is done already by alun_utils.create_squad but i write here too to make it clear how to
        se_squad.scripted_target = 'esc_smart_terrain_TODO'
        
        -- memorize the squad id to be used later to retrieve the squad object to check if still exists and for the target functor
        -- also since now squad_id has a valid value it will no longer be "falsy" so this block won't be executed on the next status functor run
        squad_id = se_squad.id
    end
    
    -- get the server object of the squad
    local se_squad = alife():object(squad_id)
    
    -- if no object is found with that id, it means the squad has been destroyed (happens automatically when all of its members are killed)
    -- in other words, the stage is complete and we can go to the next one
    if not se_squad then
        tsk.stage = 1
    end
end

function task_functor.mytask_target_f(task_id,field,p,tsk)
	-- if stage 0 (army squad alive), target it
	-- warning, this may run before the squad has been created, however since nil is a valid value for target functor (no marker) it's ok
	-- but be careful and never expect the functions to be called in a specific order
	
	if tsk.stage == 0 then
		return squad_id
	end
	
	-- if stage 1 (army squad dead), target fanatic
	-- some npc and items have defined a "story_id" to make easier getting their objects in script, in fanatic case it's "esc_2_12_stalker_fanat"
	-- as you can see in his spawn section define in \configs\creatures\spawn_sections_escape.ltx
	if tsk.stage == 1 then
		return story_objects.object_id_by_story_id('esc_2_12_stalker_fanat')
	end
end

Now when you start the task, the squad will appear at the bridge and after killing it you will get a quest update notification and now you have a quest marker on fanatic.

To make quests be available at specific npc and allow completion when talking to them back you'll have to edit the task section definition.

First of all the npc must have a special task manager dialog, then the task must be named "npc_section_task_XXX" where XXX is whatever you want (in vanilla coc and most other mods it must actually be a number sequential to other tasks by same npc, so if you have X_task_1, X_task_2 and X_task_3 already, you new task MUST be named X_task_4, in anomaly you can use whatever name you want as long the prefix "X_task_" is respected). To add the task to the pool available at fanatic (he already has the task manager dialog):

task_manager.ltx

[esc_2_12_stalker_fanat_task_mytask]
status_functor 	= mytask_status_f
target_functor 	= mytask_target_f

title 	= st_mytask_title
descr 	= st_mytask_descr

; the dialog used by npc to introduce the task, must be defined in xml
job_descr = st_mytask_job_descr

; the dialog used by npc when turning the quest in, must be defined in xml
; can be omitted and npc will use a generic "good job" response
task_complete_descr = st_mytask_task_complete_descr

; for task manager handled quests, the stage does matter, it is needed by the npc to know if he should show the "the job is done" dialog to turn it in
; in our case, we want it only after the army squad is dead, so stage 1
stage_complete = 1

Also now that the task is handled by the task manager, inside functors you can access the value tsk.task_giver_id which is the id of the npc that gave you the task, so for example the target functor can be changed to:

mytask.script

function task_functor.mytask_target_f(task_id,field,p,tsk)
	if tsk.stage == 0 then
		return squad_id
	elseif tsk.stage == 1 then
		return tsk.task_giver_id
	end
end

Now if you go talk to fanatic and ask for jobs, it will propose also the new task, you can go now kill the army and come back to turn it the task, you have now a fully working task, but the reward is missing, since fanatic is not sidorovich he would pay you, to do this we write the on_complete line, which defines what happens when task is completed.

task_manager.ltx

[esc_2_12_stalker_fanat_task_mytask]
status_functor 	= mytask_status_f
target_functor 	= mytask_target_f

title 	= st_mytask_title
descr 	= st_mytask_descr

job_descr = st_mytask_job_descr
task_complete_descr = st_mytask_task_complete_descr

stage_complete = 1

on_complete = %=reward_random_money(5000:10000) =reward_stash(true) =complete_task_inc_goodwill(50:stalker)%

on complete is a condlist, which is basically a "dynamic" config line but with tons of gotchas, so when in doubt just copypaste from exisitng ones and edit values accordingly

on_complete = %=reward_random_money(5000:10000) =reward_stash(true) =complete_task_inc_goodwill(50:stalker)%

actually means that when the condlist is parsed (in this case when task is completed) it will execute the functions:

-- give player from 5000 to 10000 cash (modified by economy settings)
xr_effects.reward_random_money(nil, nil, {"5000","10000"})

-- give a stash location
xr_effects.reward_stash(nil, nil, {"true"})

-- give 50 goodwill with "stalker" (loners) faction 
-- (modified by economy settings)
xr_effects.complete_task_inc_goodwill(nil, nil, {"50","stalker"})

To find all possible functions check xr_effects.script, but you can make your own too as long you edit xr_effects (not recommended) or add functions from your script into it a and b depend on how the condlist is parsed, so unless you know what you're doing (and if you need to read this guide you probably don't) ignore them.

NPC Creation

Written by GhenTuong#1278 Formatted and edited by @nltp_ashes

Table of content :

• Chapter 1 : Configuration
• Chapter 1.A : Creating your own mod files for character creation
• Chapter 2 : NPC section
• Chapter 3 : NPC profile
• Chapter 4 : Squad and smart terrain
• Chapter 5 : Spawn
• Chapter 5.A : Spawn by script
• Chapter 5.B : Spawn by adding to simulation.ltx

Chapter 1 : Configuration

What is stalker configuration:
All dynamic objects are configured in _unpacked\configs\system.ltx.
To not overcrowd the file, different configurations are grouped into multiple files, and they are included in system.ltx.

What files to pay attention to:

• _unpacked\configs\creatures\*
• _unpacked\configs\gameplay\*
• _unpacked\configs\misc\squad_descr\*
• _unpacked\configs\scripts\*

Chapter 1.A: Creating your own mod files for character creation

While it's possible to configurate the files already present, for independent addons it's advisable to create your own files.

One of the methods is by including your files:

NB: "my_mod_name" will stand for whatever name you choose. - for example if you want to call your mod "revolution", the file names would be: - spawn_sections_revolution.ltx - character_desc_revolution.xml - dialogs_revolution.xml - npc_profile_revolution.xml - squad_descr_revolution.ltx

File : _unpacked\configs\creatures\spawn_section.ltx

• you add: #include "spawn_sections_my_mod_name.ltx"

Folder : _unpacked\configs\creatures\

• you add a file called: spawn_sections_my_mod_name.ltx

File : _unpacked\configs\system.ltx

• you add in the line of [dialogs]: dialogs_my_mod_name
• you add in the line of [profiles]:
  • in the line of "files": npc_profile_my_mod_name
  • in the line of "specific_characters_files": character_desc_my_mod_name

Folder : _unpacked\configs\gameplay\

• you add the files:
  • character_desc_my_mod_name.xml
  • dialogs_my_mod_name.xml
  • npc_profile_my_mod_name.xml

Folder : _unpacked\configs\misc\squad_descr

• you add a file: squad_descr_my_mod_name.ltx (This one you doesn't need an include, squad_descr.ltx does it automatically)

For your own custom files, you can copy-paste already exisiting ones and rename them. In that case, be careful to delete everything in your copied file from the old file, except the opening and closing node. For exemple, in dialogs file, <game_dialogs> and </game_dialogs> have to remain, and your code has to be inbetween of these two nodes.

Chapter 2 : NPC section

File : _unpacked\configs\creatures\spawn_sections_bar.ltx

[bar_visitors_barman_stalker_trader]:stalker_silent
$spawn                      = "respawn\bar_visitors_barman_stalker_trader"
character_profile           = bar_visitors_barman_stalker_trader
story_id                    = bar_visitors_barman_stalker_trader

This is an example of a section.

• [bar_visitors_barman_stalker_trader]:stalker_silent
  Section name is bar_visitors_barman_stalker_trader, and inherits section stalker_silent.
  bar_visitors_barman_stalker_trader has all the lines of stalker_silent.
  It's useful for making multiple sections having similar lines and only have a few different lines to avoid mistakes and tediousness when modifying.

• $spawn
  This on is not important, ignore.

• character_profile
  You will later create a profile for the character in _unpacked\configs\gameplay.

• story_id
  Used for scripting. Instead of searching every object in the game to find this character, you can get him from story objects storage.

Now you make your section. Let's call your new character "han_yue_ling". We create it right in this file.

File : _unpacked\configs\creatures\spawn_sections_bar.ltx

[han_yue_ling]:stalker
character_profile           = han_yue_ling
story_id                    = han_yue_ling

I set it up to inherit "stalker" because I don't need the additional configuration in "stalker_silent" (see "stalker_silent" in _unpacked\configs\creatures\spawn_sections_general.ltx).

Chapter 3 : NPC profile

File : _unpacked\configs\gameplay\npc_profile_mlr.xml

<!-- Bar -->
<character id="bar_visitors_barman_stalker_trader">
	<class>bar_visitors_barman_stalker_trader</class>
</character>

Very simple. Just make your NPC profile in a similar way.

File : _unpacked\configs\gameplay\npc_profile_mlr.xml

<character id="han_yue_ling">
	<class>han_yue_ling</class>
    <specific_character>han_yue_ling</specific_character>
</character>

Now we create a character description.

File : _unpacked\configs\gameplay\character_desc_bar.xml

<!-- Barkeep -->
<specific_character id="bar_visitors_barman_stalker_trader" team_default = "1">
	<name>bar_barmen_name</name>
	<icon>ui_inGame2_barman</icon>
	<map_icon x="1" y="4"></map_icon>
	<bio>bar_barmen_bio</bio>
	<class>bar_visitors_barman_stalker_trader</class>
	<community>trader</community>
	<terrain_sect>stalker_terrain</terrain_sect>
	<money min="1000000" max="1000000" infinitive="1"></money>
	<rank>18490</rank>
	<reputation>2408</reputation>
	<visual>actors\barman\barman</visual>
	<!-- <snd_config>characters_voice\human\stalker_1\</snd_config> -->
	<crouch_type>-1</crouch_type>
	<supplies></supplies>
	<start_dialog>bar_visitors_barman_stalker_trader_start_dialog</start_dialog>
	<actor_dialog>dm_init_batender</actor_dialog>
	<!-- LTTZ -->
	<actor_dialog>barkeep_living_legend</actor_dialog>
	<actor_dialog>barkeep_100rads</actor_dialog>
	...
</specific_character>

• <!-- Barkeep -->
  This is how you make comment in xml files. <!-- -->.

• <specific_character id="bar_visitors_barman_stalker_trader" team_default = "1">
  Character description id.

• <name>bar_barmen_name</name>
  Stalker name. The game will try to map this id with the strings in _unpacked\configs\text\*.

• <icon>ui_inGame2_barman</icon>
  Same as <name></name> but in _unpacked\configs\ui\textures_descr\*.

• <bio>bar_barmen_bio</bio>
  Not important. Can just leave it <bio></bio>.

• <class>bar_visitors_barman_stalker_trader</class>
  Character profile. Not to confuse with character description.
  Multiple character descriptions can be linked to one character profile.
  When a stalker is spawned, it will randomly pick one of the character descriptions.
  So although they are the same "stalker_level_4" they have different names, icons, models, voices.

• <community>trader</community>
  Faction. dolg,freedom,stalker,army, etc.

• <terrain_sect>stalker_terrain</terrain_sect>
  Not important. Just keep it as is.

• <visual>actors\barman\barman</visual>
  Stalker model.

• <crouch_type>-1</crouch_type>
  No idea. Maybe it's because Barman has unique animations? I don't create this line in my character description.

• <supplies></supplies>
  Items that are guaranteed to be given to the stalker when he is spawned.

• <start_dialog>bar_visitors_barman_stalker_trader_start_dialog</start_dialog>
  Stalkers will speak this dialog when initiating dialog.

• <actor_dialog>dm_init_batender</actor_dialog>
  One of the dialog options that actor can choose after <start_dialog></start_dialog>.

So we make our character description like this. Don't forget to create a name string id, an icon id, making your unique model actors\han_yue_ling.ogf.

File : _unpacked\configs\gameplay\character_desc_bar.xml

<specific_character id="han_yue_ling" team_default = "1">
	<name>han_yue_ling_name</name>
	<icon>han_yue_ling_icon</icon>
	<map_icon x="1" y="4"></map_icon>
	<bio></bio>
	<class>han_yue_ling</class>
	<community>dolg</community>
	<terrain_sect>stalker_terrain</terrain_sect>
	<money min="1000000" max="1000000" infinitive="1"></money>
	<rank>18490</rank>
	<reputation>2408</reputation>
	<visual>actors\han_yue_ling</visual>
	<snd_config>characters_voice\human\stalker_1\</snd_config>
	<supplies></supplies>

	<!-- No dialog. For now. -->
</specific_character>

Chapter 4 : Squad and smart terrain

You don't spawn a stalker object alone. Stalkers and monsters always come with squads. Even when there is only one NPC, you still have to put him in a squad.

Squad configuration is in _unpacked\configs\misc\squad_descr\*.

File : _unpacked\configs\misc\squad_descr\squad_descr_bar.xml

[bar_visitors_barman_stalker_trader_squad]:online_offline_group
faction                     = stalker
npc                         = bar_visitors_barman_stalker_trader
target_smart                = bar_visitors
spawn_point                 = bar_barman_spawn
story_id                    = bar_visitors_barman_stalker_trader_squad
always_arrived              = true

• [bar_visitors_barman_stalker_trader_squad]:online_offline_group
  No need to explain again. See Chapter 1.

• faction = stalker
  Squad faction.

• npc = bar_visitors_barman_stalker_trader
  NPCs that are guaranteed to be spawned in the squad. You put object section here. See Chapter 1.

• target_smart = bar_visitors
  The squad will try to reach this smart terrain and will stay here forever. Can use a condlist to change target.

• spawn_point = bar_barman_spawn
  Where squad members appear when they are online. I don't find it useful so never use it.

• story_id = bar_visitors_barman_stalker_trader_squad
  Squad story id. See Chapter 1.

• always_arrived = true
  I don't know, never use it.

So we make our squad:

File : _unpacked\configs\misc\squad_descr\squad_descr_bar.xml

[han_yue_ling_squad]:online_offline_group
faction                     = dolg
npc                         = han_yue_ling
target_smart                = bar_dolg_general
story_id                    = han_yue_ling_squad

You can always find smart terrain name in here. _unpacked\configs\scripts\<level name>\smart\<smart terrain name>.

Example: _unpacked\configs\scripts\bar\smart\bar_dolg_bunker.ltx

Chapter 5 : Spawn

There are two ways to spawn your NPC : by script, or by adding your NPC to the correct smart terrain in simulation.ltx.

Chapter 5.A : Spawn by script

Make a new file in _unpacked\scripts\ like this:

File : _unpacked\scripts\han_yue_ling.script

-- Bind function actor_on_first_update() to callback "actor_on_first_update"
function on_game_start()
	RegisterScriptCallback("actor_on_first_update",spawn_han_yue_ling)
end

function spawn_han_yue_ling()
	-- Check if having info "han_yue_ling_init"
	if not has_alife_info("han_yue_ling_init") then
		-- Check if squad does not exist.
		if not get_story_se_object("han_yue_ling_squad") then
			-- Get smart terrain "bar_dolg_general"
			local smart = SIMBOARD.smarts_by_names["bar_dolg_general"]
			-- Spawn squad "han_yue_ling_squad"
			local squad = SIMBOARD:create_squad(smart,"han_yue_ling_squad")
		end
		-- Check if squad exist (spawned successfully).
		if get_story_se_object("han_yue_ling_squad") then
			-- Give info so the game won't spawn another squad every time loading a save file.
			give_info("han_yue_ling_init")
		end
	end
end

• --[[ some comment ]] or -- some comment
  Is how you make comment lines in lua script.

Start a new game or load your save files and the npc will be spawned and stay around the campfire in duty headquarters yard.

NB: Potential bug

If you have multiple spawns of the same NPC, make sure that you gave the squad a story ID - the script checks for this story ID and if it can't find the ID it will spawn endlessly the same NPC.

Chapter 5.B : Spawn by adding to simulation.ltx

Locate the file simulation.ltx, in _unpacked\configs\misc\. Inside of that file, you can locate the smart terrain where you want your NPC to spawn, and add your NPC to the list.

File : _unpacked\configs\misc\simulation.ltx

...
[bar_dolg_general]
bar_dolg_general_petrenko_stalker_squad
bar_dolg_general_zoneguard_stalker_squad
duty_sim_squad_advanced                 = 1
duty_sim_squad_novice                   = 1
duty_sim_squad_veteran                  = 1
dolg_medic_squad
han_yue_ling_squad                      ; add your NPC to the list

...

Note that this method of spawning the NPC will not force the NPC to stay there, and you might need a script, or a logic scheme to force the NPC to stay at that smart terrain.

I will make more advanced guides if there are enough modders who are interested.

TASK GUIDE

Written by @nltp_ashes

Table of content :

• I. INTRODUCTION
• II. TASK CONFIG
• II.A. GENERALITIES
• II.B.1. TASK LIFECYCLE (IN CONFIG)
• II.B.2. TASK LIFECYCLE (IN SCRIPT)
• II. TASK CONFIG
• III. STARTING THE TASK
• III.A. USING THE GAME'S DYNAMIC RANDOM TASKS
• III.B. USING YOUR OWN FUNCTIONS
• IV. TASK FUNCTORS
• IV.A. TASK TITLE FUNCTOR
• IV.B. TASK DESCRIPTION FUNCTOR
• IV.C. TASK TARGET FUNCTOR
• IV.D. TASK STATUS FUNCTOR

I. INTRODUCTION

Before we start, keep in mind tasks often take part at the junction of a lot of the game's systems : dialogs, NPCs, squads, smart terrains and what not.

This guide aims to address how to work on tasks, and specifically tasks, while sometimes making connections to other things. You'll most likely need to get familiar (either before, or along the way) with those other systems in order to create your task, depending on how complex you want it.

Make sure to check the Anomaly Modding Book to see if guides exists for these other aspects not detailed here.

Without going into details, to create a task, you will at least need to play with the following files.

• gamedata/configs/misc/task/task_manager.ltx:
  where your task config will be;

• gamedata/configs/text/eng/st_my_task.xml:
  where the translation strings for your task will be;

• gamedata/scripts/my_task.script:
  where your task functors will be.

For more complex tasks, you may also need to create custom squads of NPCs, for which you will need to create the following file.

• gamedata/configs/misc/squad_descr/squad_descr_my_task.ltx:
  where your custom squads configs will be.

• gamedata/configs/gameplay/dialogs_my_task.xml:
  where your custom dialogs will be.

Note that, to ensure maximum compatibility, it is highly discouraged to edit and redistribute modified vanilla files. Instead, you can use DLTX and DXML to modify those files at runtime, ensuring high compatibility with other addons.

II. TASK CONFIG

Your task is in reality composed of two things. A config side, and a script side. First, we'll take a look at the config side.

II.A. GENERALITIES

Here is a complete task config, or section. It contains all the information to allow the game to use your task. Some of these fields are optional, but I highly recommend you use all of them to ensure a good experience for the player.

File: gamedata/configs/misc/task/task_manager.ltx

[my_task]

title_functor           = my_task_title_f
descr_functor           = my_task_descr_f
target_functor          = my_task_target_f
status_functor          = my_task_status_f

...

icon                    = ui_inGame2_Skat_1
storyline               = false

stage_complete          = 1
...

• title_functor
  Name of a function (defined in task_functor namespace). This function will be used to display the name of your task in the PDA. See more in IV.A..

• descr_functor
  Name of a function (defined in task_functor namespace). This function will be used to display a description of the player's current objective in the PDA. See more in IV.B..

• target_functor
  Name of a function (defined in task_functor namespace). This function will be used to place a marker on the player's objective in the PDA. See more in IV.C..

• status_functor
  Name of a function (defined in task_functor namespace). This function will manage your task logic as a whole. It will be responsible for spawning objects, checking objective completion, progressing the task, etc. See more in IV.D..

• icon
  ID of a texture description. This is the icon for the task that will be displayed in the PDA and in the dialogs.

• storyline
  Boolean. true if your task is a main mission (golden marker on the PDA) or false if your task is a secondary mission (gray marker on the PDA).

• stage_complete
  Number. Stage at which the task is considered completed. A task starts at stage 0 and can have any number of stages you want.

II.B.1. TASK LIFECYCLE (IN CONFIG)

Worth a special attention are on_init, on_complete and on_fail. Those are three condlists executed at key moments of your task.

At these events, you might want to give the player a reward, or take an item away from the player, etc. There honestly a lot you can do here, so I'll just breeze over the commonly used things.

File: gamedata/configs/misc/task/task_manager.ltx

[my_task]
...
on_init                 = %+my_task_is_active%
on_complete             = %-my_task_is_active +my_task_is_finished =reward_random_money(5000:10000) =reward_stash(true)%
on_fail                 = %-my_task_is_active%

• on_init
  Condlist. List of functions to execute when the player has just taken the task.

• on_complete
  Condlist. List of functions to execute when the player has just completed the task.

• on_fail
  Condlist. List of functions to execute when the player has just failed the task.

You can replace the content of % ... % by any arrangement of the following :

• +some_info_portion
  This will give an info portion called some_info_portion to the player.
  You need to replace some_info_portion with the name of an info portion of your liking.

• -some_info_portion
  This will remove an info portion called some_info_portion from the player.
  You need to replace some_info_portion with the name of an info portion of your liking.

• =reward_random_money(min:max)
  This will reward the player with a sum of money between min and max.
  You need to replace min and max with number values.

• =reward_stash(true)
  This will reward the player with a stash location.

• =reward_item(sec)
  This will reward the player with a specific item that has sec for a section.
  You need to replace sec with the name of an existing section.

• =reward_random_item(sec_1:sec_2)
  This will give the player one item among the list of sections passed (you can list as many sections as you want, separated by a :.
  You need to replace sec_1, sec_2, etc. with the name of an existing section.

• =remove_item(sec)
  This will remove one item that has sec for a section from the player's inventory. No effect if the player does not have the item.
  You need to replace sec with the name of an existing section.

• =complete_task_inc_goodwill(value:faction)
  This will give the player value points of goodwill with faction faction.
  You need to replace value with a number value and faction with the name of a faction.

• =fail_task_dec_goodwill(value:faction)
  This will remove from player value points of goodwill with faction faction.
  You need to replace value with a number value and faction with the name of a faction.

This list is not exhaustive, and there is plenty more you can do. As you'll soon read in II.B.2., you can even define your own functions to use in these condlists.

II.B.2. TASK LIFECYCLE (IN SCRIPT)

The condlists we just had a look at will try to call the functions they contain in the xr_effects namespace.

Because of how S.T.A.L.K.E.R. scripts are set up, this means you can define your own functions (in your script) to handle those events :

File: gamedata/configs/misc/task/task_manager.ltx

[my_task]
...
on_init                 = %=my_task_init()%
on_complete             = %=my_task_complete()%
on_fail                 = %=my_task_fail()%

File: gamedata/scripts/my_task.script

function xr_effects.my_task_init(actor, npc, params)
   give_info("my_task_is_active")
   
   -- some other code you might want can be added here
end

function xr_effects.my_task_complete(actor, npc, params)
   disable_info("my_task_is_active")
   give_info("my_task_is_finished")
   xr_effects.reward_random_money(actor,npc,{"5000","10000"})
   xr_effects.reward_stash(actor,npc,{"true"})
   
   -- some other code you might want can be added here
end

function xr_effects.my_task_fail(actor, npc, params)
   disable_info("my_task_is_active")
   
   -- some other code you might want can be added here:
end

This allows you for a finer control over what happens at the events, though this has the downside of putting config-related stuff in script, which isn't ideal.

III. STARTING THE TASK

It is important to note that there are multiple ways to make the player start your task.

III.A. USING THE GAME'S DYNAMIC RANDOM TASKS

You can utilize the game's dynamic random tasks system. For this, you need to :

• name your task according to the following contract <npc_name>_task_<task_name>
• add <actor_dialog>dm_ordered_task_dialog</actor_dialog> to the task giver's dialogs (if the NPC doesn't already have it)
• add <actor_dialog>dm_ordered_task_completed_dialog</actor_dialog> to the task giver's dialogs (if the NPC doesn't already have it)

Once that's done, you will be able to add a few things to your task config to allow you more control.

File: gamedata/configs/misc/task/task_manager.ltx

[<npc_name>_task_my_task]
...
job_descr               = st_my_task_job_descr
task_complete_descr     = st_my_task_complete_descr
repeat_timeout          = 0
precondition            = {-my_task_is_finished} true, false
...

• job_descr
  ID of a translation string. This translation string will be the task description displayed before taking the task.

• task_complete_descr
  ID of a translation string. This translation string will be the text displayed after the player says "The job is done.".

• repeat_timeout
  Number. Time before the player can complete that same task again.

• precondition
  Condlist. If the condlist is evaluated as true, the player can take the task, if it is evaluated as false, then the task won't show up.

By default, those tasks are repeatable, but if you check for an info portion in the precondition, and give that info when the player completes the task, you can make sure the task is played only once (useful for storyline tasks).

III.B. USING YOUR OWN FUNCTIONS

Alternatively to using the dynamic random tasks, you can define your own dialog, that will eventually call a function you defined, which will be responsible for starting the task. This will complexify your code, it'll also increase the amount of code to maintain, but it'll allow you more control over the dialogs leading to taking up a tasks, and how the tasks themselves are started.

There are many ways to start the task using that technique, but the two important things you should know are :

1. To execute a script function in a dialog, you use <action>namespace.function</action> inside a phrase of a dialog.
   File: gamedata/configs/gameplay/my_task_dialogs.xml

   <dialog id="my_dialog_id">
           <phrase_list>
               <phrase id="0"> <!-- actor -->
                   <text>st_my_string_id</text>
                   <action>my_task.start_task</action>
               </phrase>
           </phrase_list>
       </dialog>
   

2. You define that function in your script :
   File: gamedata/scripts/my_task.script

   function start_task(actor, npc)
       -- You can check conditions or do anything before giving the task if you want
       
       -- Get the server object of the NPC giving the task 
       -- If you can that function from a dialog, 'npc' will be the person the player is talking to, which can be used as a task giver
       local task_giver = get_story_se_object("my_task_giver")
   
       -- Start the task called 'my_task' with 'task_giver' as the NPC giving the task
       task_manager.get_task_manager():give_task("my_task", task_giver:id())
   end
   

IV. TASK FUNCTORS

On the script side of your task, as previously explained, you will need a few functions to get your task rolling. Those are :

1. task_functor.my_task_title_f(...)
2. task_functor.my_task_descr_f(...)
3. task_functor.my_task_target_f(...)
4. task_status_functor.my_task_status_f(...)

I recommend you use a table to manage what has been done in your task. You can define this table at the beginning of your my_task.script.

File: gamedata/scripts/my_task.script

MY_TASK_CACHE = {}

Note that you'll need to persist this table, otherwise your task will break with loading a save-game :

File: gamedata/scripts/my_task.script

--- Function used to store information in the save file.
--- @param m_data table
--- @return nil
function save_state(m_data)
    m_data.my_addon_name_my_task_cache = MY_TASK_CACHE
end

--- Function used to load information stored in the save file.
--- @param m_data table
--- @return nil
function load_state(m_data)
    MY_TASK_CACHE = m_data.my_addon_name_my_task_cache or {}
end

IV.A. TASK TITLE FUNCTOR

This function manages the task's title. In the end, this function must return a string, a string that will be displayed in the PDA (among other places) as the task's name.

While generally, the name of the task itself won't change, having it as a functor allows you to have a dynamic title, in case you'd like to change it in the middle of the task for some reason.

File: gamedata/scripts/my_task.script

--- Function used to retrieve the title of the mission (displayed in the PDA).
--- @param task_id number
--- @param field string
--- @param p any
--- @param tsk CGameTask
--- @return string
function task_functor.my_task_title_f(task_id,field,p,tsk)
    return game.translate_string("st_my_task_title")
end

Alternatively, since the task's title isn't really meant to change, you can hard-code it in the task's config.

File: gamedata/configs/misc/task/task_manager.ltx

[my_task]
...
title                   = st_my_task_title
...

IV.B. TASK DESCRIPTION FUNCTOR

In the PDA, the task's description will be whatever string is returned by this function.

A few recommendations :

• write your description in a passive way, and assume doesn't know what it did before and what it needs to do
• always give a bit of context as to what the player has done : You have found and retrieved the documents.
• describe what is the new objective the player has to achieve : Return the item to Dushman, in Deadcity.

You can have the description evolve anyway you want, either by checking the task's stage, or by checking info portions, etc.

File: gamedata/scripts/my_task.script

--- Function used to retrieve the description of the mission (displayed in the PDA).
--- @param task_id number
--- @param field string
--- @param p any
--- @param tsk CGameTask
--- @return string
function task_functor.my_task_descr_f(task_id,field,p,tsk)
    if has_alife_info("the_player_has_done_something_really_bad") then
        return game.translate_string("st_send_player_to_brazil")
    end

    if tsk.stage == 0 then
        return game.translate_string("st_my_task_stage_0_description")
    end
    
    if tsk.stage == 1 then
        return game.translate_string("st_my_task_stage_1_description")
    end
end

Similarly to the task's title, the description can also be hard-coded in the task's config. Although this isn't recommended, since your task will rarely have only one stage, and each stage should have its own description.

File: gamedata/configs/misc/task/task_manager.ltx

[my_task]
...
descr                   = st_my_task_description
...

IV.C. TASK TARGET FUNCTOR

This function will be used to place a marker on the player's objective in the PDA. You can code this function as you see fit.

All you have to keep in mind is, if the function returns nil, no marker will be shown on the PDA, if it returns a number, the game will try to find an object with an ID matching the number, and it'll place a marker on it.

Unfortunately, this means that you cannot just place markers anywhere, and that markers can exclusively be placed on top of game objects.

File: gamedata/scripts/my_task.script

--- Function used to retrieve the target of the mission (marker displayed (or not) in the PDA).
--- @param task_id number
--- @param field string
--- @param p any
--- @param tsk CGameTask
--- @return number
function task_functor.my_task_target_f(task_id,field,p,tsk)
    if tsk.stage == 0 then
        -- Stage 0 target : the quest item
        local quest_item_se = get_story_se_object("my_task_quest_item")
        return quest_item_se and quest_item_se.id
    end
    
    if tsk.stage == 1 then
        -- Stage 1 target : the NPC that gave the task
        return tsk.task_giver_id
    end
end

IV.D. TASK STATUS FUNCTOR

The task status functor is a function that is automatically called every few seconds, by the game's task manager. This is where the heart of your task will be. Spawning objects, check if they still exist, if they have been killed, progressing the task, etc. Everything lies here.

There isn't really a convention for how to write tasks, but as a personal recommendation, I suggest you write your code using a sort of "return early" pattern. That means you write your code from top and downwards, and return as soon as a condition to progress isn't met.

File: gamedata/scripts/my_task.script

--- Function used to manage the mission logic as a whole.
--- @param tsk CGameTask
--- @param task_id number
--- @return string
function task_status_functor.my_task_status_f(tsk,task_id)
    if tsk.stage == 0 then
        -- logic of the first stage
    end
    
    if tsk.stage == 1 then
        -- logic of the second stage
    end
end

There are a few important things you need to manipulate in this function :

1. The task stage : you can use tsk.stage as both a getter and a setter for the stage :

   • local stage = tsk.stage to get the current stage;
   • tsk.stage = 2 to set the current stage to stage 2;

   -- We get the current stage of the task
   local stage = tsk.stage
   
   -- If we're in the correct stage, and the player has a certain info portion
   if stage == 0 and has_alife_info("the_player_has_done_something") then
       -- We progress the task to stage 1
       tsk.stage = 1
   end
   

2. The return value :

   • use return (aka return nil) to stop the execution of the function "for now";
   • use return "complete" to force-complete the task;
   • use return "fail" to force-fail the task;

   If you use "return" or "return nil" (which is the same), the task manager will not execute the rest of the code for now - but it will have no effect on the status of the task. Remember the task manager calls your status functor every few seconds, so it will quickly call it again.

   -- While the player hasn't done anything, we return (aka we wait)
   if not has_alife_info("the_player_has_done_something_great") and not has_alife_info("the_player_has_done_something_really_bad") then
       return
   -- If the player has done something great, the task is complete
   elseif has_alife_info("the_player_has_done_something_great") then
       return "complete"
   -- If the player has done something bad, the task is failed
   elseif has_alife_info("the_player_has_done_something_really_bad") then
       return "fail"
   end
   

Dialogues

Written by ComradeCatilina

Chapter 1 : Concerned Files

The files you need are:

File : _unpacked\configs\gameplay\character_desc_*.xml

In this file you have to add your dialogue to the concerned NPC. This is done by adding the line: <actor_dialog>XXX</actor_dialog>

File : _unpacked\configs\gameplay\dialogs_*.xml

In this file you construct the dialogue tree.

File : _unpacked\configs\gameplay\text\eng\st_dialogs_*.xml

In this file you write the text of your dialogue.

NB: If you're doing a custom NPC, it's advisable to not use preexisting files but to add your own. You can check under "NPC creation" how to include your own files. IF you're adding dialogue to a preexisting NPC, you will have to add your <actor_dialog>XXX</actor_dialog> in his file, but you can use a 'custom dialogs_*.xml' file for the dialogue tree.

File : _unpacked\configs\gameplay\text\eng\st_dialogs_*.xml doesn't need to be included.

Chapter 2 : Basic dialogue tree

As an example, we will use a preexisting NPC - the barman in Rostok.

You will find him in

File : _unpacked\configs\gameplay\character_desc_bar.xml

under the name "bar_visitors_barman_stalker_trader".

Step 1

Add <actor_dialog>my_custom_dialogue_1</actor_dialog>

"my_custom_dialogue_1" is an example, you can use whatever you want as long as it's unique.

Step 2

We create the dialogue tree:

In this example we will use a preexisting dialogs file, although it's strongly recommended to add your own file to your mod.

File : _unpacked\configs\gameplay\dialogs_bar.xml

The basic structure of a dialogue tree is the following:

<dialog id="my_custom_dialogue_1">		
				
		<phrase_list>
      
				<phrase id="0">
					<text>my_custom_dialogue_1_0</text>
					<next>1</next>
				</phrase>
        
				<phrase id="1">
					<text>my_custom_dialogue_1_1</text>					
				</phrase>	
      
		</phrase_list>
  
	</dialog>		

• <dialog id="my_custom_dialogue_1">

This is the link between <actor_dialog>my_custom_dialogue_1</actor_dialog> and the dialogue tree.

• <phrase_list>

Your whole dialogue tree has to be inbetween these nodes.

• <phrase id="0">

This is one branch of the tree. Note that 0 is the first line of the actor and 1 is the NPC's answer.

The exception is <start_dialog> - the dialogue shown if you talk to the NPC the first time. In this case 0 is the NPC and 1 is the actor.

• <text>my_custom_dialogue_1_0</text>

my_custom_dialogue_1_0 is the text string which will get translated by the game.

• <next>1</next>

This handles which dialogue branch will be shown next.

NB: notice that every node starts with and is closed with a "/" :

This is essential - take care to always close your nodes or the game will crash on boot.

Step 3

Now we need to add the text of the dialogue.

In order to do that, add in your

File : _configs\gameplay\text\eng\st_dialogs_*.xml

<string id="my_custom_dialogue_1_0">
		<text>Hy barkeep, I made my own dialogue.</text>
	</string>
  
<string id="my_custom_dialogue_1_1">
		<text>Very impressive.</text>
	</string>  
  

Now, if you load your mod, you whould see an dialogue option for the barkeep in Rostok "Hy barkeep, I made my own dialogue." and he will answer "Very impressive."

Chapter 3 : Advanced dialogue tree

Now we will add multiple choice answers for the player:

<dialog id="my_custom_dialogue_1">		
				
		<phrase_list>
      
				<phrase id="0">
					<text>my_custom_dialogue_1_0</text>
					<next>1</next>
				</phrase>
        
				<phrase id="1">
					<text>my_custom_dialogue_1_1</text>
          		                 <next>2</next>
               				 <next>3</next>       
			  	</phrase>
      
         			  <phrase id="2">
					<text>my_custom_dialogue_1_2</text>
					<next>4</next>
				</phrase>
        
        			<phrase id="3">
					<text>my_custom_dialogue_1_3</text>
					<next>5</next>
				</phrase>
      
       				 <phrase id="4">
					<text>my_custom_dialogue_1_4</text>
					
				</phrase>
      
       				 <phrase id="5">
					<text>my_custom_dialogue_1_5</text>
					
				</phrase>
      
		</phrase_list>
  
	</dialog>

Now after the first exchange, the player will have two options to answer: either option 2 or 3.

If the player chooses option 2, the NPC will answer with branch 4, and if the player chooses option 3, the NPC will answer with branch 5.

Note that if the dialogue is over, there is no in the branch. The player will again see the starting dialogue options.

Chapter 4 : The four horsemen of dialogue and the executor

The four major tools to handle a dialogue tree are the following:

• <has_info>XXX</has_info>

Dialogue tree or dialogue branch will only show if the actor has the XXX info.

• <dont_has_info>XXX</dont_has_info>

Dialogue tree or dialogue branch will only show if the actor doesn't have the XXX info.

• <give_info>XXX</give_info>

Gives the actor the XXX info during a dialogue.

Alternatives are:

• on_death = %+XXX%

This has to be added in the squad_descr file, and gives the info on the death of the squad it is linked to.

• give_info("XXX")

This gives the info during the execution of a script.

• <precondition>my_script_for_mod.my_condition</precondition>

Dialogue tree or dialogue branch will only show if the condition is met.

"my condition" is the name of a function which has to be defined in the script file "my_script_for_mod.script".

This tool is quite versatile, and is only limited by your coding skills (and the limitations of lua).

Last but not least, we have:

• <action>my_script_for_mod.my_action</action>

This will trigger a function "my_action" defined in the script file "my_script_for_mod.script".

This can be used to give a quest or to give the player an item, money etc.

Chapter 5 : Putting everything together

Let's imagine the actor has a quest consisting in bringing a tuna can "conserva" to the barkeep.

So we have to write two functions, the first for the (so that you can only submit the quest if you have a tuna can in your inventory) and the second in order to give the tuna can.

Create the file "my_script_for_mod.script"

File : _gamedata\scripts\my_script_for_mod.script

First we create the precondition:

function my_condition()
  if db.actor:object("conserva") then
    return true
  end
  return false
end  

"my_condition" can be named as you like, take care to use the same name in the script file and in the precondition.

We can see that the script works as follows: it returns "false" by default, except if the condition is met: if (inside the actors inventory is an item called conserva) then return true

Now we create the transfer

function my_action(first_speaker, second_speaker)
  dialogs.relocate_item_section_from_actor(first_speaker, second_speaker, "conserva")
  dialogs.relocate_money_to_actor(first_speaker, second_speaker, 7500)
end 

This will remove the tuna can from the player's inventory (but not add it to the NPC) and give the player 7500 roubles.

Now that we added these two tools we can write the dialogue:

Example 1: Curtailing the dialogue tree

We will use the dialogue tree in Chapter 2 as an example.

In this example, you want the dialogue tree to be available to the player only if he has a tuna can in his inventory.

But, you also want to show the dialogue tree only if the player accepted a mission beforehand (imagine another dialogue tree before this one in which the dialogue branch gave the mission and the info):

• this is done by adding <has_info>my_tuna_mission_given</has_info>

Now this option will only show if the player also has the info "my_tuna_mission_given".

But you also want to show the dialogue only once to the player, or else he will repeatatly be able to exchange tuna for money.

• this is done by adding <dont_has_info>my_tuna_mission_done</dont_has_info> and later in the dialogue <give_info>my_tuna_mission_done</give_info>

Now this dialogue will only be shown until the player resolves the quest.

In order to affect the dialogue tree, and not specific branches, the conditions, has_info, dont_has_info have to be before before <phrase_list>.

<dialog id="my_custom_dialogue_1">
  
	<precondition>my_script_for_mod.my_condition</precondition>
    
   	<has_info>my_tuna_mission_given</has_info>
  
   	<dont_has_info>my_tuna_mission_done</dont_has_info>
  
		<phrase_list>
      
				<phrase id="0">
					<text>my_custom_dialogue_1_0</text>
					<next>1</next>
				</phrase>
        
				<phrase id="1">
					<text>my_custom_dialogue_1_1</text>
					
					<action>my_script_for_mod.my_action</action>
					
					<give_info>my_tuna_mission_done</give_info>	
				
				</phrase>	
      
		</phrase_list>
  
	</dialog>	

Example 2: Curtailing the dialogue branches

In the precedent example we saw how to hide the dialogue option until the conditions are met. Now we will do the same, but with a dialogue branch.

Again, we want this dialogue tree to be open only after the quest has been given and only until the quest has been resolved. This means we keep has_info and dont_has_info.

But this time, precondition will be used to show the dialogue option / branch only if the player has the tuna in his inventory.

In this example, the text is written directly inside the tree to ease the comprehension.

<dialog id="my_custom_dialogue_1">		
	<has_info>my_tuna_mission_given</has_info>
  
  	<dont_has_info>my_tuna_mission_done</dont_has_info>		
  
		<phrase_list>
      
				<phrase id="0">
					<text>ABOUT YOUR TUNA MISSION</text>
					<next>1</next>
				</phrase>
        
				<phrase id="1">
					<text>YES, WHAT ABOUT IT?</text>
          		                 <next>2</next>
               				 <next>3</next>       
			  	</phrase>
      
         			  <phrase id="2">
                  
         				<precondition>my_script_for_mod.my_condition</precondition>        
                  
					<text>I HAVE YOUR TUNA</text>
					<next>4</next>
				</phrase>
        
        			<phrase id="3">
					<text>I NEED MORE TIME TO FIND YOUR TUNA</text>
					<next>5</next>
				</phrase>
      
       				 <phrase id="4">
					<text>THANK YOU VERY MUCH</text>
                 
					<action>my_script_for_mod.my_action</action>
					
					<give_info>my_tuna_mission_done</give_info>
                 
				</phrase>
      
       				 <phrase id="5">
					<text>NO PROBLEM</text>
					
				</phrase>
      
		</phrase_list>
  
	</dialog>

Now every instrument is playing together. After initiating the dialogue by saying "about your tuna mission", the NPC will reply "what about it?"

Now the player has two options: branch 2 which will only show if he has a tuna can in his inventory and branch 3 which will always show.

If the player uses branch 2 - it will lead to branch 4 which triggers the tuna - money exchange and gives the info which will prevent the code to show the dialogue again (as we added <dont_has_info>my_tuna_mission_done</dont_has_info>)

Of course you can use has_info and dont_has_info also in the different dialogue branches in order to make the dialogue tree more complex.

NB: I never tried it, but I believe you cannot use precondition, has_info and dont_has_info to curtail the NPC replies. The NPC should always have only one .

Reference

Reference chapters are lists of things. Have fun.

Terminology

Engine

ODE

ODE (Open Dynamics Engine) - is an open physics engine distributed for free as a dynamically linked library. Its main components are an Absolute-Solid Dynamics system and a collision detection system.

Source Code

A-Life

A-Life (Artificial Life) - artificial intelligence system. More About

Smart Terrain

A smart-terrain is a specific script class in the game, which is used to populate locations. Smarts organize jobs for NPS, implement logic for certain exclusive characters, respawn NPS and monsters, and organize emission shelters for NPS.

OpenAL

OpenAL (Open Audio Library) - cross-platform application programming interface (API) for working with audio data. A key feature is working with sound in 3D space and using EAX effects.

Object Types

Dynamic object

Any movable object (which can be displaced from its place regardless of the scripts)

Example:

Distinguishing features:

• Has a bone collision

Static object

Any static object at the level

Example (in this case, part of the collision level):

Distinguishing features:

• Does not have a bone collision

Progressive Meshes

One of the methods of dynamic level of detail

MU (Multiply Usage) Objects

Needed for automatic creation of LOD at compilation stage

HOM (Hierarchical Occlusion Mapping)

One way to optimize the level

Sector

Sectors are a connected empty closed area bounded by static geometry and portals. In X-Ray 3D Engine, level geometry is not involved in sector creation, it uses HOM objects for this purpose.

Portal

Portals are "windows" through which (and only through which) an observer can see the insides of other sectors.

object_hud

HUD (Head-Up Display) - is a set of graphical interfaces and decorative elements located in the foreground and/or in the game world, which are designed to clearly and quickly convey to the player the necessary information from the game at a given point in time, without interfering with the gameplay experience.

In stalker modding, object_hud is a model in front of the player in the hands of the character. Usually it is a model of a weapon, grenades, etc.

Example:

Distinguishing features:

• Does not have a bone collision

object_world

Model, in-game world (NPC weapons, 3rd-person view). The difference from the _hud model is that the _world must have a collision to calculate the interaction with the game.

Example:

Distinguishing features:

• Has a bone collision
• Dynamic object

Animations

object_hud animations

Animations for the _hud object

Material

Material

In the X-Ray engine, game material is a set of surface properties, namely:

• texture
• shader used in the game
• shader used by the level compiler
• set of sounds of interaction with objects

Main Folders And Files

Root folder

fsgame.ltx

Contains paths to folders with the necessary files

appdata

logs

This is where the game logs are created and stored (log of loading objects, textures, etc.)

savedgames

This is where game saves are created and stored. Inside are files with the extensions .scop and .scoc.

screenshoots

This is where game screenshots are created and stored

shaders_cache

This is where the game shader cache is created and stored

"username".ltx

This file describes the game settings.

bin

Contains the .exe files of the game renders, the configuration for OpenAL and .dll libraries

db

Contains packaged game files. This folder has a higher priority of files, which means that if there is no file in the gamedata folder, the game will look for it here

gamedata

Folder with game files

Folders

ai

Contains the .efd files needed for the AI

anims

Contains .anm, .anms files for camera animation and .ppe files for postprocessing

configs

Contains .ltx for configuration files and .xml for text

levels

Contains the necessary files for the levels

meshes

Contains .ogf, .dm, .omf file needed for models and skeleton animation

scripts

Contains .script files for game scripts

shaders

Contains various files for shaders

sounds

Contains .ogg files for various music, sounds, ambient, etc.

spawns

Contains a file all.spawn - it describes all spawn spots on locations

textures

Contains .dds textures

Files

gamemtl.xr

Contains game materials

lanims.xr

Contains animations of lights

particles.xr

Contains Particles

senvironment.xr

Contains settings for sound environment zones

shaders.xr

Database of the shaders used by the graphics engine

shaders_xrlc.xr

Database of shaders used by the level compiler

textures.ltx

Contains pathes to all textures

tools

Contains some resources for modding, like a version icon for addons, a resource converter and .bat files for unpacking .db files

File Formats

This section describes the extensions that are found in the game files and the SDK.

General

Configuration and script files

Textures

Shaders

Models

Animations

Archives and Resource Packages

Game level

Starting here, the details of the formats are written. You are encouraged to use links from the tables above to jump directly to the format you are interested in

Binary files

About

This article is an introduction to binary files.

Before reading the other articles in the "File Formats" category, you should read this one first.

Structure

In binary files, bytes are represented in reverse order.

For example, the number 0x12345678 in a file would look like this: 78 56 34 12.

Data types

Let's introduce the notation of data types.

These notations will be used in other articles.

In some files a value may not be stored in the whole byte, but only part of it (e.g. 4 bits).

As a result, one byte will store two values.

In articles about binary files, sizes will be specified either in bits or in bytes.

Strings necessarily have a null byte at the end, which indicates that the string has ended. For example: "test_string0x0".

As a result, the length of the string is equal to the number of characters in it + 1 (null byte).

Blocks

In X-Ray, some binary files are in RIFF format.

Such files have blocks (also called chunks or sections).

A block is binary data with a header.

Block structure

You can see from the identifier what is stored in a particular block.

If the compression is set to 0x0000, the block is uncompressed, and if it is set to 0x8000, the block is compressed by the Huffman method.

You can use a program from xray_re_tools (trunk\garbage\lzhuf\lzhuf.c) to decompress compressed blocks.

In the files of the final version of the game most blocks are uncompressed.

The size of the block content indicates only the number of bytes of data (not including identifier, compression and size bytes).

Binary block data can be represented by nested blocks.

Sources

Source

.anm (Animated paths)

About

A set of coordinates, which works as an animation of the actor's camera movement. It is also used for anomalies, which need to be given a path.

Technical information

• Order of rotation: YXZ

Interpolation types

• TCB
• BEZIER_2D
• BEZIER_1D
• LINEAR
• HERMITE

Programs editing this file

• Blender (X-Ray Addon)
• SDK 0.7

bump#.dds

About

Corrects DXT compression errors in .bump

Technical information

Format

• RGB - Error correction for normal map (bump.dds) - Not necessary if you're using good quality normal map. It's generated with SDK
• A - height map; used for parallax, if the use of it was turned on when setting up the texture

The engine currently supports the following compressions

• DXT5
• BC7

Can be generated by

• Bump Generator
• SDK 0.7

bump.dds

About

The bump map is a regular normal map in A(BGR) format (typical for DXT5_nm compression format). The developers used this order for a very simple reason - DXT compression "spoils" the texture much less, since the alpha channel is not subjected to compression and remains almost in its original form.

Technical information

Format

• R - Glossiness (Glossiness, aka inverted roughness. It works best in stalker, and allows for using better BRDF)
• G - Normal Z (Unused in Anomaly 1.6.0)
• B - Normal Y (DIRECTX format.)
• A - Normal X

The engine currently supports the following compressions

• DXT5
• BC7

Can be generated by

• Bump Generator
• SDK 0.7

.cform (Collision Form)

About

Contains a solid map structure. All tangible objects with materials live here. Because of this, the game knows with what sound and property objects should react when they are hit by bullets or walked on

Technical information

• Format version: 4

The file consists of one block, which contains the following

BBox

BBox describes the entire map, including absolutely all static objects. The BBox diagonal is represented by two vertices that have the same format as the others:

Triangle

Programs editing this file

• Blender (X-Ray Addon)
• SDK 0.7

Sources

Source

.dds (DirectDraw Surface)

About

DDS is most often used to store textures and is used in many 3D applications, as well as in modern 3D games. It allows you to store textures both in compressed and uncompressed form.

Technical information

Format

• RGB - Diffuse colour
• A - Alpha (Used for translucent/transparent shaders like glass/grass)

The engine currently supports the following compressions

• DXT1
• DXT5

Programs editing this file

• Any program that works with .dds files (Example: Paint.net or GIMP)

detail_map_name_(with bump or bump#).dds

About

Same as a regular .dds texture, needed as an extra map in a .thm

Technical information

The same as the .dds. But overlaid on top of an existing texture, for more detail

Example:

Programs editing this file

• Any program that works with .dds files (Example: Paint.net or GIMP)

.details

About

Detailed objects (grass, cigarette butts, construction debris) on the level

Technical information

• Format version: 3

General structure - file blocks

It consists of three RIFF sections (blocks):

Block order in version 3: 0x1, 0x2, 0x0

One cell (slot) is a parallelepiped.

The dimensions of all cells along the X and Z axes are the same and equal to 2 meters.

The height of the slot (the dimensions of the parallelepiped along the Y axis) in all the slots is individual.

slot in the Level Editor

Blocks

Block 0x0 (header)

Block 0x1 (meshes)

A block consists of nested blocks.

The nested block identifier is the mesh index of the detailed object.

Nested block data is a mesh in .dm format

Block 0x2 (slots/cell table)

The block stores cells (slots).

The slots in this block are written alternately.

Up to four meshes of detailed objects can be attached to each slot.

The mesh index of a detailed object can be in the range [0 ... 62] (63 is no mesh).

One slot's data is stored in 16 bytes (128 bits), which store the following:

As you can see from the table, each slot has 16 density values.

Each of the four meshes has four density values (for the four corners of the slot).

The density values within a slot are interpolated from the density values of the slot corners.

Let us denote the densities as follows:

• a0 - density for the left front corner of the slot

• a1 - density for the right front corner of the slot

• a2 - density for the left rear corner of the slot

• a3 - density for the right rear corner of the slot

If you look at the slot from above, the densities will look like this:

Mesh density, slot view from above

Restrictions are imposed on the position of slots along the Y axis.

The lower limit is -200 meters.

And the allowed range: from -200 meters to 619 meters (0.2 * 4095 - 200).

The maximum height of the slot (parallelepiped) is: 25.5 (0.1 * 255).

The upper boundary of the slot is equal to: the lower boundary + the height of the slot.

Programs editing this file

• Blender (X-Ray Addon)
• SDK 0.7

Sources

Source

.dm (Detail Model)

About

Effect of a dynamic weather environment (e.g., rain or lightning)

Technical information

It works like this: UV descends down the Y coordinates to the texture

Format limitations

• Must have one material
• Does not support antialiasing

General structure

Structure description

Shader name

Texture name

Flags

Minimum size

Maximum size

Number of vertices

Number of indexes

Vertices

The vertices are stored sequentially.

The structure of a single vertex:

Restrictions are imposed on the vertices:

1. one vertex may have only one texture coordinate. When saving the model in *.dm, a vertex that has two (or more) texture coordinates is converted into two (or more) vertices.
2. Their number should not be more than 65536, because their triangle indices are stored in 2 bytes.

Indexes

The indices of the vertices by which triangles are formed.

The indexes are stored sequentially.

The index structure:

Programs editing this file

• Blender (X-Ray Addon)
• X-Ray Export Tool (Object Tool)
• SDK 0.7

Sources

Source

.efd (Evaluation Function Data)

About

Table of AI heuristic parameters, contains constants for fine-tuning A-Life. They are used as input parameters in scripts.

Example

anomalydetectprobability.efd

[values]
offset_0: value_0 = 1
offset_4: value_1 = 1
offset_8: value_2 = 2
offset_12: value_3 = 8
offset_16: value_4 = 3
offset_20: value_5 = 49
offset_24: value_6 = 9
offset_28: value_7 = 79
offset_32: value_8 = 20
offset_36: value_9 = 100
offset_40: value_10 = 1
offset_44: value_11 = 2
offset_48: value_12 = 0
offset_52: value_13 = 1
offset_56: value_14 = 19.9940643310547
offset_60: value_15 = 59.9821968078613
offset_64: value_16 = 99.9703216552734
offset_68: value_17 = 19.9940643310547
offset_72: value_18 = 59.9821968078613
offset_76: value_19 = 99.9703216552734
offset_80: value_20 = 29.9910984039307
offset_84: value_21 = 59.9821968078613
offset_88: value_22 = 89.9732894897461
offset_92: value_23 = 69.9792251586914
offset_96: value_24 = 74.9777450561523
offset_100: value_25 = 84.9747772216797
offset_104: value_26 = 89.9732894897461
offset_108: value_27 = 89.9732894897461
offset_112: value_28 = 89.9732894897461
offset_116: value_29 = 79.9762573242188
offset_120: value_30 = 79.9762573242188
offset_124: value_31 = 79.9762573242188
offset_128: value_32 = 79.9762573242188
offset_132: value_33 = 79.9762573242188
offset_136: value_34 = 79.9762573242188
offset_140: value_35 = 39.9881286621094
offset_144: value_36 = 49.9851608276367
offset_148: value_37 = 79.9762573242188

Programs editing this file

• Evaluation Function Consctructor

Sources

Source

.err

About

Contains information about geometry errors during level compilation with xrLC.exe

Technical information

It consists of three blocks:

Blocks

All vertices in the file are stored in the following structure:

Block 0x0 (vertices)

Contains vertices that were glued during compilation.

Block structure:

Block 0x1 (edges)

Contains edges that were deleted during compilation.

Block structure:

Structure of a single edge

Block 0x2 (triangles)

Contains broken triangles (the area of which is close to 0.0).

Block structure:

Structure of a single triangle

Programs editing this file

• Blender (X-Ray Addon)
• SDK 0.7

Sources

Source

.geom

The format was disassembled by Haper (not completely disassembled, adjustments are needed)

About

Contains all visible map geometry. It contains all vertices with normals and coordinates for textures and indexes for building geometry, as well as synchronization.

Technical information

The file consists of the following blocks

Types of variables

Map compiler version (the block is the same for all maps)

Vertex description

Vertex description block

A few words about the vertex format. As you already know, there are several vertex description blocks in the file. Not all objects in the game are the same: you have to specify coordinates of lightmaps for brushes, and coordinates of textures for trees can be simplified. Therefore, vertices specified in different blocks may be different. The vertex format is specified using several structures - this is the standard D3D vertex buffer format. That is, the file contains ready assembled vertex buffers for D3D:

At the very beginning of any vertex are the coordinates of its placement, so the vertex format does not include a description of the coordinates. There are only three vertex formats in the 2215 maps:

Vegetation

Thus, the total length of one vegetation vertex equals 32 bytes.

Brush

The total length of one brash vertex is 36 bytes.

Entity

The total length of one vertex of an entity is 36 bytes. Based on this, we get, for example, this view of the vertex:

Brush

Indexes description

Index description block

Index: Word(2) . The number of indexes must always be a multiple of three, because triangles are constructed using indexes.

Synchronization description

(what they synchronize is still a mystery to scientists)

Synchronization block

Synchronization unit

Sources

Source

.hom (Hierarchical Occlusion Mapping)

About

HOM is a geometry cutter, which is a mesh and is needed to increase performance. This file is created during level compilation.

Technical information

Blocks

Consists of two blocks:

Block description

Block 0x0 (header)

Block 0x1 (mesh data)

Contains the data of the triangles, which are written one by one.

The data is for one triangle:

Possible values of the "two sided" option: 0x0, 0x1

The polygon indices are not saved, but they can easily be generated, since all vertices are saved so that the polygon indices are in ascending order.

The first triangle will be: 0, 1, 2, second: 3, 4, 5, third: 6, 7, 8, etc.

Programs editing this file

• Blender (X-Ray Addon)
• SDK 0.7

Sources

Source

level

About

Contains all the essentials. This contains light sources, object descriptions, names of their corresponding textures and shaders, portals, and sectors.

Technical information

• Format version: 14

General structure - file blocks

Map compiler version (the block is the same for all maps)

Description of portals (the block for all maps is the same and contains no data)

Light sources

Light Source

Coronas of light sources

Corona of the light source

Textures

Texture

Note: the zero texture is specified without the file name and consists only of the symbol #0. So, after the field "number of textures" right after the symbol #0, do not be alarmed :)

Sectors

Programs editing this file

• Blender (X-Ray Addon)
• SDK 0.7

Sources

Source

LTX files

About

LTX files are basically ini files with some custom additions. They are located all over the gamedata/configs and are used for, well, configs.

Here's how ltx config might look like:

#include "tables/gun_*.ltx"

[some_nice_gun]
recoil              = 0.8
boosts              = a, b, c, d    ; list
fancy_feature       = {=is_night()} true, false

[some_other_gun]
...

From this example we can see some fancy ltx features:

1. #include preprocessor command. This command basically merges the file into this config. Many of the configs are included into system.ltx this way, so you can access almost all sections through ini_sys handler.
2. Wildcard imports - * in include statement corresponds to any text, so the given include will include both gun_ak.ltx and gun_m4.ltx. This feature was developed for Anomaly, so you may not find it in other mods.
3. Name of the section in square brackets - this is referred in scripts as section_name or just section.
4. Key-value pairs. Values may include comma-separated lists.
5. Comments start with ;.
6. fancy_feature uses something called "condlist". Refer to condlists manual to understand this bs.

Programs editing this file

• Any text editor
  • There are also extensions for VSCode for .ltx (LTX Support Extension by AziatkaVictor)

.object

About

These files are intended for the X-Ray SDK to store 3D content in its original, uncompressed, lossless form. They are source files that store information before compilation into other game compressed formats.

Technical information

The format can store the following basic data (the list is not complete)

• meshes
• materials
• bones
• skeleton animations

Possibilities and limitations of the .object format

One *.object file can store:

• one or more meshes if it has no skeleton and only one meshes if it has a skeleton
• one or more materials
• a skeleton can be absent, or it can hold at least one
• a skeleton can store a minimum of 1, a maximum of 64 bones (for X-Ray SDK 0.4)
• skeleton animations may not be present, or one or more animations may be stored
• skeleton animations do not support Scale keys
• each mesh can have one or more materials
• each mesh must have one UV scan
• each material can store only one texture

Programs editing this file

• Blender (X-Ray Addon)
• X-Ray Export Tool (Object Tool)
• Ogf Editor by ValeroK - (Only as a converter!)
• SDK 0.7

Sources

Source

.ogg

About

The sound format used by the game engine

Technical information

• Supports up to 44.100 Hz
• Audio format:
  • Mono audio format (For the game world)
  • Stereo audio format (To play in the player's head)
• Audiocodek: Vorbis

Programs editing this file

• Any sound editor that supports .ogg (But it won't write comments into the chunks!)
• Sound Attribute Viewer And Tweaker or OGG Editor
• SDK Sound Editor - Only source .wav file

.omf (Open Motions Format)

About

A specialized S.T.A.L.K.E.R. game format containing animations. This is a separate dedicated file used in conjunction with .ogf models. Was created in order to optimize process when some different models use the same list of animations.

Technical information

They are in RIFF format. That is, the file is divided into chunks. The omf file consists of two chunks:

• 0xE - stores animations (rotation, movement of bones)

• 0xF - stores the Bone Parts and animation parameters.

These chunks can be found inside the ogf files. In other words, an omf file is a slice of an ogf file that is moved to an external file. The structure of the 0xE and 0xF chunks in ogf is identical to those in omf.

The structure of the 0xE chunk

This chunk consists of nested chunks. The first nested chunk is the one with the identifier 0x0. The zero chunk stores an unsigned 32-bit integer number. This number indicates the number of animations in the omf file. The identifier of each subsequent chunk is one more than the previous one. That is, 0x0 is followed by 0x1, then 0x2, 0x3, etc. All the chunks following 0x0 contain animations. Description of the nested chunk that stores the animations The animation name comes first, which is a string ending with a null byte. Next is an unsigned 32-bit integer, which specifies the number of animation frames. The following data is the dice transforms. For each bone, rotation, movement, and flags are stored. Flags come first. Flags is an unsigned 8 bit integer. The first bit of this byte indicates if the movement is modifiable. If the bit is 1, then the movement has values throughout all frames. If the bit is 0, then the movement has only one value for the entire animation interval. This is done to optimize it so that it doesn't store a bunch of identical keys, but instead has a single value. The second bit of this byte indicates whether the rotation is static (not changing throughout the animation). The third bit is the High Quality flag. If it is 0, then the position has an 8-bit representation, otherwise it is 16-bit. Next comes the information about the rotation. What will be written to the file next depends on the flags. If the second bit of the flag is 0, the file will contain the following: One rotation value as a quaternion with two-byte signed components. That is, QXYZ, each 2 bytes, for a total of 8 bytes. And if the second bit of the flag is 1, then the following follows: crc32 sum as a 4 byte unsigned integer. And after that come the rotation quaternion values for each frame. The format of rotation is the same as described above (the same 8 bytes). Now comes the movement information. If the first bit of the flag is 1, then follows a 32-bit unsigned integer, which is the crc32 sum. This is followed by three eight-bit numbers, which indicate the position of the bone on the x, y, z axes. These positions are written for each frame. That is, the positions should be read in a loop, which is repeated as many times as the number of frames contains the animation. After all these positions are data about the initial conditions of movement: Amplitude or size of movement. These are three float numbers (4 bytes each). And then there is the initial value of movement. These are also 3 float numbers. These initial conditions are stored in a single instance for each bone in this animation. That is, these values do not change throughout the animation. If the first bit of the flag is 0, there is one move value for all frames. This movement is stored in 3 float numbers (4 bytes each).

Below is a pseudocode that describes one animation:

name = string
length = uint32
for bone in bones {
    flags = uint8
    translate_present = flags(0)    // get bit 0
    rotate_absent = flags(1)    // get bit 1
    high_quality = flags(2)    // get bit 2
    if rotate_absent {
        quaternion = int16, int16, int16, int16    // Q, X, Y, Z
    } else {
        motion_crc32 = int32
        for (i=0, i<length, i++) {
            quaternion = int16, int16, int16, int16    // Q, X, Y, Z
        }
    }
    if translate_present {
        motion_crc32 = int32
        if high_quality {
            for (i=0, i<length, i++) {
                translation = int16, int16, int16    // X, Y, Z
            }
        } else {
            for (i=0, i<length, i++) {
                translation = int8, int8, int8    // X, Y, Z
            }
        }
        translate_size = float, float, float    // X, Y, Z
        translate_init = float, float, float    // X, Y, Z
    } else {
        translate = float, float, float    // X, Y, Z
    }

Chunk structure 0xF

Stores bone parts and animation parameters. The code that describes this chunk is shown below:

params_version = uint16 // parameter format version
partition_count = uint16 // number of bone parts
for (i=0, i<partition_count, i++) {
    partition_name = string // name of the bone part
    bone_count = uint16 // number of bones in this bone part
    for (j=0, j<bone_count, j++) {
        if params_version == 3 {
            bone_name = string // bone name
            bone_id = uint32 // bone ID
        }
    }
    motion_count = uint16 // number of animations
    for (j=0, i<motion_count, j++) {
        // animation parameters
        motion_name = string
        motion_flags = uint32
        bone_or_part = uint16
        motion = uint16 // animation identifier from the 0xE chunk
        speed = float32
        power = float32
        accrue = float32
        falloff = float32
    }
}

Programs editing this file

• Blender (X-Ray Addon)
• OMF Editor by ValeroK

Sources

Source

.seq (Sequence)

About

Text file that is used to create a simple animation texture, by recording a sequence of "frames" and a playback speed.

Example

15
ui\ui_ani_cursor_01
ui\ui_ani_cursor_02
ui\ui_ani_cursor_03
ui\ui_ani_cursor_04
ui\ui_ani_cursor_05

Order in which the textures are played will be 1234512312312345

cycled
15
ui\ui_ani_cursor_01
ui\ui_ani_cursor_02
ui\ui_ani_cursor_03
ui\ui_ani_cursor_04
ui\ui_ani_cursor_05

In this case, because of "cycled" the playback order will be 1234543212345432123454321 Speed of texture change is set in numerical format before the enumeration

The number of textures in the list is arbitrary, but the more frames, the greater the load on the engine, respectively. The name of the file is set by the name of the assigned texture (without taking the extension into account). If there is a *.dds file in the folder with the same name as the *.seq file, the engine ignores the original texture, giving priority to the *.seq file. The priority of file search by extension is as follows:

• .ogm
• .avi
• .seq
• .dds

Parameters

• The "cycled" parameter is optional if you want to loop from the first texture to the last texture and from the last texture to the first texture. If you don't write it, it will play in a normal circular loop.
• Playback speed (frames per second) (written before the list of textures)

Programs editing this file

• Any text editor

Sources

Source

.som (Sound Occluder Mesh)

About

Geometry for calculating sound propagation. Used to allow sound to pass through walls, ceilings, floors, etc. with varying strength.

Technical information

• Format version: 0

Blocks

It consists of two blocks:

The structure of the file is similar to .hom

Block 0x0 (header)

Block 0x1 (mesh data)

Polygon indices are not saved, but they can be easily generated, because all vertices are saved so that polygon indices are in ascending order.

The first triangle will be: 0, 1, 2, second: 3, 4, 5, third: 6, 7, 8, etc.

Programs editing this file

• Blender (X-Ray Addon)
• SDK 0.7

Sources

Source

.thm

About

They are used to set the parameters of .dds textures - bump, detail, and more. Without them the game does not give textures the necessary parameters, and therefore they are obtained "flat", worse than the static lighting.

Programs editing this file

• THM Editor by ValeroK or THM Editor by i-love-kfc
• SDK 0.7

XML files

About

XML files are used to save text strings used for translation. All XML files are located in gamedata/configs/text/*lang*. XML files have these properties:

1. They are saved in encoding Windows-1251. English translation won't break if you're using UTF, but russian will.
2. Every string must have an unique id assigned to it.
3. There is a single namespace for all xml files of one language. That means, no matter in which file you are saving your strings, they will be available in one place, namely game.translate_string(*id*).

XML file will look something like this:

<?xml version="1.0" encoding="windows-1251"?>
<string_table>
	<string id="nice_text_id">
		<text>Cool text inside text tags</text>
	</string>

    <string id="another_text_id">
		<text>...</text>
	</string>
    
    ...
</string_table>

Programs editing this file

• Any text editor

Crashes List

Error description

• Expression - Expression in the engine code, which gives an error
• Function - Name of the function where the error occurred
• File - File where the error occurred
• Line - Line in File where the error occurred
• Description - Possible problem description
• Arguments - Argument causing the error

Warning! This list is only for the vanilla version of the game! If you use engine edits, the logs of crashes may be different!

Models

[error]Expression    : \<no expression>
[error]Function      : CModelPool::Instance_Load
[error]File          : ..\xrRender\ModelPool.cpp
[error]Line          : 120
[error]Description   : fatal error
[error]Arguments     : Can't find model file "path and file name".

Animations

[error]Expression    : \<no expression>
[error]Function      : CKinematicsAnimated::Load::<lambda_1d323dfa2c5eacee46e042904e528af6>::operator ()
[error]File          : ..\xrRender\SkeletonAnimated.cpp
[error]Line          : 784
[error]Description   : fatal error
[error]Arguments     : Can't find motion file "path and file name".

[error]Expression    : m_Motions.size()
[error]Function      : CKinematicsAnimated::Load
[error]File          : ..\xrRender\SkeletonAnimated.cpp
[error]Line          : 857

section '(null)'
model 'path to model'

Animated Paths

[error]Expression    : \<no expression>
[error]Function      : CObjectAnimator::LoadMotions
[error]File          : ObjectAnimator.cpp
[error]Line          : 47
[error]Description   : fatal error
[error]Arguments     : Can't find motion file "path and file name".

A-Life

[error]Expression    : false
[error]Function      : CPatternFunction::vfLoadEF
[error]File          : ef_pattern.cpp
[error]Line          : 49
[error]Description   : assertion failed

[error]Expression    : false
[error]Function      : CPatternFunction::vfLoadEF
[error]File          : ef_pattern.cpp
[error]Line          : 60
[error]Description   : assertion failed

[error]Expression    : !NET.empty()
[error]Function      : CBaseMonster::net_Export
[error]File          : ai\Monsters\BaseMonster\base_monster_net.cpp
[error]Line          : 27
[error]Description   : assertion failed

Spawn

[error]Expression    : FS.exist(file_name, "$game_spawn$", *m_spawn_name, ".spawn")
[error]Function      : CALifeSpawnRegistry::load
[error]File          : alife_spawn_registry.cpp
[error]Line          : 86
[error]Description   : Can't find spawn file:
[error]Arguments     : "file name"

[error]Expression    : R_ASSERT2(file_stream.find_chunk(SPAWN_CHUNK_DATA)
[error]Function      : CALifeSpawnRegistry::load
[error]File          : alife_spawn_registry.cpp
[error]Line          : 60
[error]Description   : Cannot find chunk SPAWN_CHUNK_DATA!

[error]Expression    : R_ASSERT2(!save_guid || (*save_guid == header().guid()) || ignore_save_incompatibility()
[error]Function      : CALifeSpawnRegistry::load
[error]File          : alife_spawn_registry.cpp
[error]Line          : 111
[error]Description   : Saved game doesn't correspond to the spawn : DELETE SAVED GAME!

[error]Expression    : R_ASSERT2(chunk, "Spawn version mismatch - REBUILD SPAWN!"); or R_ASSERT2(m_chunk, "Spawn version mismatch - REBUILD SPAWN!");
[error]Function      : CALifeSpawnRegistry::load
[error]File          : alife_spawn_registry.cpp
[error]Line          : 141 or 147
[error]Description   : Spawn version mismatch - REBUILD SPAWN!

LTX

[error]Expression    : FS.exist(fn, "$game_textures$", buf, ".ini")
[error]Function      : CGameFont::Initialize
[error]File          : GameFont.cpp
[error]Line          : 96
[error]Description   : "path and ui_font_hud_01.ini"

LUA

[error]Expression    : \<no expression>
[error]Function      : CScriptEngine::lua_pcall_failed
[error]File          : ..\xrServerEntities\script_engine.cpp
[error]Line          : 204
[error]Description   : fatal error
[error]Arguments     : LUA error: ...e.r anomaly/bin/..\gamedata\scripts\"script_name".script:62: bad argument #1 to 'pairs' (table expected, got nil)

Reference

Reference chapters are lists of things. Have fun.

w_Weapon.ltx Config File

About

Configuration parameters for weapons

Parameters of the weapon are set for each sample in a separate *.ltx file, and consist of two sections (Each contains its own set of parameters):

• [wpn_name] - Main, it sets most of the parameters (for NPC and 3rd-person view).

• [wpn_name_hud] - Secondary, where you set first-person view parameters only.

Parameters of the world model

[wpn_name]: Here you can set additional characteristics of weapon from sections for example:

• identity_immunities - a section that contains damage parameters for different game difficulty levels
• weapon_probability
• default_weapon_params

General parameters

Position and Orientation of Weapons

Weapon parameters in inventory

Parameters for multiplayer (there is no multiplayer in the game, so the parameters are useless)

Particle parameters from the shot

Parameters of the upgrades/repairs

Icons of the upgrades

Parameters of the weapon itself

Shot parameters

Ammo parameters

Particle shell parameters

Aiming parameters

Parameters of the silencer

Parameters of the underbarrel grenade launcher

Aiming parameters

Misfire parameters

Wear parameters

Сamera parameters

Parameters of the camera when aiming

Parameters for AI

Weapon HUD parameters

Strafe/Inertion