Repository: SmartlyDressedGames/U3-Docs Branch: latest Commit: 897318870b5e Files: 178 Total size: 716.0 KB Directory structure: gitextract_ui58d88c/ ├── .editorconfig ├── .gitignore ├── .readthedocs.yaml ├── Makefile ├── README.md ├── _extensions/ │ └── unturned_lexer.py ├── _static/ │ ├── css/ │ │ ├── custom.css │ │ └── toctree_collapse.css │ └── js/ │ └── toctree_collapse.js ├── about/ │ ├── getting-started.rst │ ├── launch-options.rst │ └── steam-workshop.rst ├── assets/ │ ├── airdrop-asset.rst │ ├── animal-asset.rst │ ├── animation.rst │ ├── asset-bundle-custom-data.rst │ ├── asset-bundles.rst │ ├── asset-definitions.rst │ ├── asset-validation.rst │ ├── character-mesh-replacement.rst │ ├── crafting-asset.rst │ ├── crafting-blacklist-asset.rst │ ├── curated-items.rst │ ├── data-file-format.rst │ ├── effect-asset.rst │ ├── foliage-asset.rst │ ├── layers.rst │ ├── level-asset.rst │ ├── material-palette-asset.rst │ ├── mod-hooks.rst │ ├── mythical-asset.rst │ ├── object-asset.rst │ ├── outfit-asset.rst │ ├── physics-material-asset.rst │ ├── redirector-asset.rst │ ├── resource-asset.rst │ ├── road-asset.rst │ ├── server-browser-curation-asset.rst │ ├── spawn-asset.rst │ ├── stereo-song-asset.rst │ ├── tag-asset.rst │ ├── unity-upgrade.rst │ ├── vehicle-asset.rst │ ├── vehicle-physics-profile-asset.rst │ ├── vehicle-redirector-asset.rst │ ├── weather-asset.rst │ └── zombie-difficulty-asset.rst ├── conf.py ├── data/ │ ├── asset-ptr.rst │ ├── bitmask.rst │ ├── built-in-types.rst │ ├── color.rst │ ├── enum/ │ │ ├── eassettype.rst │ │ ├── ebatterymode.rst │ │ ├── eitemorigin.rst │ │ ├── eitemrarity.rst │ │ ├── eitemtype.rst │ │ ├── elightingvision.rst │ │ ├── enpcholiday.rst │ │ ├── eobjectchart.rst │ │ ├── eobjecttype.rst │ │ ├── eslottype.rst │ │ └── index.rst │ ├── flag.rst │ ├── guid.rst │ ├── master-bundle-ptr.rst │ ├── rich-text.rst │ ├── struct/ │ │ ├── index.rst │ │ └── playerspotlightconfig.rst │ └── vector3.rst ├── img/ │ └── WorkshopMapIDs.csv ├── index.rst ├── items/ │ ├── actions.rst │ ├── arrest-end-asset.rst │ ├── arrest-start-asset.rst │ ├── backpack-asset.rst │ ├── bag-asset.rst │ ├── barrel-asset.rst │ ├── barricade-asset.rst │ ├── beacon-asset.rst │ ├── blueprints.rst │ ├── blueprints_inputitem.rst │ ├── blueprints_outputitem.rst │ ├── box-asset.rst │ ├── caliber-asset.rst │ ├── charge-asset.rst │ ├── clothing-asset.rst │ ├── cloud-asset.rst │ ├── consumeable-asset.rst │ ├── detonator-asset.rst │ ├── farm-asset.rst │ ├── filter-asset.rst │ ├── fisher-asset.rst │ ├── fishing-catchable-properties.rst │ ├── food-asset.rst │ ├── fuel-asset.rst │ ├── gear-asset.rst │ ├── generator-asset.rst │ ├── glasses-asset.rst │ ├── grip-asset.rst │ ├── grower-asset.rst │ ├── gun-asset.rst │ ├── hat-asset.rst │ ├── introduction.rst │ ├── key-asset.rst │ ├── library-asset.rst │ ├── magazine-asset.rst │ ├── map-asset.rst │ ├── mask-asset.rst │ ├── medical-asset.rst │ ├── melee-asset.rst │ ├── oil-pump-asset.rst │ ├── optic-asset.rst │ ├── pants-asset.rst │ ├── placeable-asset.rst │ ├── refill-asset.rst │ ├── sentry-asset.rst │ ├── shirt-asset.rst │ ├── sight-asset.rst │ ├── storage-asset.rst │ ├── structure-asset.rst │ ├── supply-asset.rst │ ├── tactical-asset.rst │ ├── tank-asset.rst │ ├── throwable-asset.rst │ ├── tire-asset.rst │ ├── tool-asset.rst │ ├── trap-asset.rst │ ├── vehicle-lockpick-tool-asset.rst │ ├── vehicle-paint-tool-asset.rst │ ├── vehicle-repair-tool-asset.rst │ ├── vest-asset.rst │ ├── water-asset.rst │ └── weapon-asset.rst ├── make.bat ├── mapping/ │ ├── charts.rst │ ├── curated-maps.rst │ ├── editor-asset-redirectors.rst │ ├── favorite-searches.rst │ ├── level-batching.rst │ ├── level-config.rst │ └── manual-object-culling.rst ├── npcs/ │ ├── conditions.rst │ ├── currency-asset.rst │ ├── dialogue-asset.rst │ ├── introduction.rst │ ├── npc-asset.rst │ ├── quest-asset.rst │ ├── rewards-list-asset.rst │ ├── rewards.rst │ └── vendor-asset.rst ├── requirements.in ├── requirements.txt ├── sdg/ │ ├── dat-editing-code.rst │ ├── hosting-servers-using-private-workshop-files.rst │ ├── legacy-id-availability.rst │ ├── source-code.rst │ ├── test-steam-items.rst │ ├── unity-project.rst │ └── using-git.rst └── servers/ ├── bookmark-host.rst ├── command-io.rst ├── debugging-exceptions.rst ├── dedicated-workshop-update-monitor.rst ├── fake-ip.rst ├── game-server-login-tokens.rst ├── glazier.rst ├── openmod.rst ├── port-forwarding.rst ├── rocket.rst ├── server-auto-restart.rst ├── server-browser-curation.rst ├── server-codes.rst ├── server-configuration.rst ├── server-hosting-rules.rst ├── server-hosting.rst ├── server-update-notifications.rst └── steamcmd.rst ================================================ FILE CONTENTS ================================================ ================================================ FILE: .editorconfig ================================================ # EditorConfig is awesome: https://editorconfig.org/ # Special property to stop .editorconfig files search. root = true # Default values for all files. [*] indent_style = tab indent_size = 4 charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true ================================================ FILE: .gitignore ================================================ # Sphinx output folder as specified in Makefile and make.bat /_build/ # Temporary Visual Studio Code config files /.vscode/ # Generated Python files, e.g., in the _extensions directory __pycache__/ # Virtual environment files /.venv/ ================================================ FILE: .readthedocs.yaml ================================================ # Read the Docs configuration file # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details # These fields are in the order they are mentioned in the RTD docs. version: 2 # Build PDF and ePub versions for offline use (HTMLzip might be too big to build?) formats: - epub - pdf build: os: ubuntu-22.04 tools: python: "3.11" python: install: - requirements: requirements.txt sphinx: configuration: conf.py fail_on_warning: true # Make warnings more visible by forcing build to fail ================================================ FILE: Makefile ================================================ # Minimal makefile for Sphinx documentation # # You can set these variables from the command line, and also # from the environment for the first two. SPHINXOPTS ?= SPHINXBUILD ?= sphinx-build SOURCEDIR = . BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) ================================================ FILE: README.md ================================================ Unturned Documentation ====================== These are the source files for *Unturned*'s modding documentation. The built documentation is hosted by [Read the Docs](https://readthedocs.org/) here: https://docs.smartlydressedgames.com/ Offline Downloads ----------------- PDF and ePub versions of the documentation can be [downloaded](https://readthedocs.org/projects/unturned/downloads/) for offline use. Contributing ------------ Anyone can contribute towards *Unturned*'s modding documentation. This repository has three branches – **latest**, **stable**, and **old-markdown-archive** – although contributions should only be made towards the "latest" branch. - **latest**: Always has the latest documentation, including upcoming features that might not be available on the current version of the game. - **stable**: Occassionally updated with the additions to the "latest" branch. - **old-markdown-archive**: Contains old documentation, in markdown files (rather than reStructuredText). This documentation does not appear on the online documentation site, and is only kept for historical purposes. Its contents may be removed in the future. The online documentation pages are generated from .rst (reStructuredText) files. These files are stored in root, but are organized into folders based on where those files appear in the table of contents. For example, the [level-asset.rst](/assets/level-asset.rst) file is located in the "assets" folder. ### Styleguide Most documentation files are formatted similarly. Some important notes: - Content block directives can be used to add notes, warnings, tips, and other admonitions. - Internal links should use the `:ref:` command, usually pointing towards a custom anchor. - Properties in the asset manual pages use one of two formats. Older pages follow a `**Name** *data type*: Description` format. Depending on the data type, it may be hyperlinked instead, or may include required (or possible) values. Newer pages follow a table-based format. These formats should not be mixed on the same page, but continuing to use the legacy format on pages that have not been converted yet is acceptable. - Images from the Unity editor should crop out any unnecessary information. This usually includes the Title Bar (which includes details such as the Unity version, project name, and window buttons), and the Toolbar. - The `code-block` directive can be used to display example code with syntax highlighting. Common languages include `cs`, `json`, `text`, `shell`, `bat`, and `unturneddat` (alias: `unturnedasset`). - Including links to our Unturned Wiki (`https://unturned.wiki.gg/`) can be helpful. Wiki articles linked in the Unturned Documentation should have the "[Category:Pages linked from Unturned Documentation](https://unturned.wiki/wiki/Category:Pages_linked_from_Unturned_Documentation)" hidden tracking category added to them. Building the Docs ----------------- This section explains how to build a local copy of the documentation. Our documentation is written in [reStructuredText](https://www.writethedocs.org/guide/writing/reStructuredText/) and converted to HTML through [Sphinx](https://github.com/sphinx-doc/sphinx). We recommend using [Visual Studio Code](https://code.visualstudio.com/) with the [reStructuredText extension](https://docs.restructuredtext.net/) (by LeXtudio Inc.), and the [Esbonio extension](https://docs.esbon.io/en/latest/index.html) (by Swyddfa) to benefit from live preview and syntax highlighting. Use the same version of Python as configured in `.readthedocs.yaml`. If you have multiple Python versions installed, you may need to manually specify the Python Interpreter that should be used. 1. Clone the Unturned Docs repository: ```shell git clone https://github.com/SmartlyDressedGames/Unturned-Docs.git ``` 2. Change directory to the Unturned Docs repository: ```shell cd Unturned-Docs ``` 3. *(Optional)* Set up a virtual environment. Virtual environments prevent potential conflicts between the Python packages installed in `requirements.txt` and any Python packages installed on your system. 1. Create the virtual environment: ```shell py -3.11 -m venv .venv ``` 2. Activate the virtual environment: ```shell .\.venv\Scripts\Activate.ps1 ``` 3. Your terminal prompt will show `(venv)` at the beginning if activation worked. 4. Download packages from `requirements.txt`: ```shell pip install -r requirements.txt ``` Alternatively, `pip-sync` can be used to ensure installed packages are *exactly* the same – by adding, upgrading, or removing any packages as necessary. **Doing this outside of the virtual environment is not recommended:** ```shell pip-sync requirements.txt ``` 5. Build the documentation: ```shell .\make html ``` Alternatively, you can build the documentation by running `sphinx-build` manually. This command is more cross-platform: ```shell sphinx-build -b html ./ _build/html ``` You can now browse the documentation by opening `.../Unturned-Docs/_build/html/index.html` in your web browser. If Esbonio was installed, you can also preview the documentation in Visual Studio Code. Configure Esbonio for a virtual environment --------------------------------------------- Esbonio v1.0.0 in a virtual environment on Windows may fail to import packages from the venv and instead used Esbonio's bundled Python environment. This causes misleading `ModuleNotFoundError` errors to appear for packages installed in the virtual environment. You can force Esbonio to use the virtual environment by configuring your `.vscode/settings.json`: ```json { "esbonio.sphinx.pythonCommand": { "command": ["${venv:.venv}"] } } ``` Updating the `requirements.txt` file ------------------------------------ Packages (including specific versions) can be pinned in `requirements.in`. This file is used to automatically generate `requirements.txt`. Run the following command to generate a new `requirements.txt` file afterwards: ```shell pip-compile requirements.in ``` Locally updating the TOC ------------------------ Sometimes, the Table of Contents will fail to update after changes have been made. This is an issue with the Esbonio extension, but it can be safely ignored as it should only affect your local preview of the project pages. If needed, you can force Esbonio to rebuild these pages. Delete the files at `%APPDATA%\Code\User\workspaceStorage\...\swyddfa.esbonio\sphinx`, run `make html`, and restart the Sphinx language server (e.g., by closing and reopening Visual Studio Code, or by clicking the "Sphinx" button in the bottom-right). ================================================ FILE: _extensions/unturned_lexer.py ================================================ """ unturned_lexer ~~~~~~~~~~~~~~ Lexer for Unturned's .dat and .asset files. https://pygments.org/docs/lexerdevelopment/ """ __all__ = ['UnturnedLexer'] from pygments.lexer import RegexLexer, bygroups from pygments.token import * class UnturnedLexer(RegexLexer): name = 'UnturnedDat' aliases = ['unturneddat', 'unturnedasset'] filenames = ['*.asset', '*.dat'] tokens = { 'root': [ (r'("(?:\\.|[^"])*")(?:(\s*)(//.*)$)?', bygroups(String, Whitespace, Comment)), # Quoted key or value – optionally, a comment (inline) can be matched too. (r'(^\s*)(//.*)$', bygroups(Whitespace, Comment)), # Comment (newline). (r'(^\s*)(\w+)\b', bygroups(Whitespace, Name.Class)), # "Key" in a key-value pair, or a "flag". (r'(^\s*)([\[\]\{\}])', bygroups(Whitespace, Name.Decorator)), # Brackets (dictionaries, lists). (r'true|false', Name.Builtin), # Boolean. (r'(#)([a-fA-F0-9]{6})', bygroups(Operator, Number)), # Color (hex triplet). (r'[-,\(\)]', Operator), # Punctuation for numbers (negatives, commas, vector3). (r'\b(\d+\.?\d*|\d*\.?\d+)\b', Number), # Number (integer, float) – this doesn't capture values such as "1." or ".1" currently. It could be changed to do so, but we may need to make separate rules for integers and floats, and possibly GUIDs as well. (r'\S+', Text), # Match remaining non-whitespace. (r'\n|\s+', Whitespace), # Match remaining whitespace – line breaks must be matched first, otherwise \s+ is too greedy and breaks preceding rules relying on whitespace. ] } def setup(sphinx): sphinx.add_lexer("unturneddat", UnturnedLexer) sphinx.add_lexer("unturnedasset", UnturnedLexer) ================================================ FILE: _static/css/custom.css ================================================ /* Custom tweaks to the Read the Docs Sphinx Theme. * Less generic styling should be placed in its own stylesheet. */ /* Tables should take up the entire available horizontal space within their container. */ .wy-table-responsive table { width: 100%; } /* COMMENTED OUT - Wrapping table contents. * This was the "intended fix" before simply maxing table width. * May be worth revisiting the idea for mobile devices, where horizontal scrolling can be cumbersome. *//* @media screen and (min-width: 769px) { .wy-table-responsive { overflow: visible; } .wy-table-responsive table td { white-space: normal; } } */ /* Fix unreadable text when selection version from sidebar. */ select option { background: #343131 !important; } ================================================ FILE: _static/css/toctree_collapse.css ================================================ /* CSS for toctree_collapse.js script. * TOC sections are "collapsed" by default, and only displayed when they've been "toggled". */ .wy-menu-vertical .caption { cursor: pointer; } .wy-menu-vertical .caption .caption-text:before { content: "❯"; /* ⮞ ⮚ ❯ */ display: inline-block; transition: transform 0.25s; transform-origin: 25% 50%; width: 16px; height: 32px; } .wy-menu-vertical .caption.toggled .caption-text:before { transform: rotate(90deg); } .wy-menu-vertical .caption + ul { display: none; } .wy-menu-vertical .caption.toggled + ul { display: block; } ================================================ FILE: _static/js/toctree_collapse.js ================================================ // Allows for collapsing TOC sections. // Styling handled by toctree_collapse.css stylesheet. $(function() { let browsing = false; // Is the reader currently on a page included in the TOC? // Selects elements from the navigation menu (TOC). const headings = document.querySelectorAll(".wy-menu-vertical .caption[role=heading]"); headings.forEach(caption => { const ulist = caption.nextElementSibling; // Toggle state when clicked. caption.addEventListener("click", () => { caption.classList.toggle("toggled"); }); // Expand current section be browsed. if (ulist.classList.contains("current")) { caption.classList.add("toggled"); browsing = true; } }); // If the reader isn't browsing, just expand the first section instead. if (browsing == false) { headings[0].classList.add("toggled"); } }); ================================================ FILE: about/getting-started.rst ================================================ .. _doc_getting_started: Getting Started =============== To get started with creating mods for *Unturned*, or hosting your own multiplayer server, certain tools need to be downloaded first. This page provides an explanation for the different types of tools you may need – depending on what you are trying to do. Installing Unturned ------------------- *Unturned* must be downloaded in order to create, publish, and update mods. The game can be downloaded for free from `Steam `_. Not only do the game files include some of the tools necessary for creating your own custom content, but the game's official assets can also be used as an example when creating your own items, objects, or other game assets. Adding *Unturned* to your Steam Library will also add the *Unturned Dedicated Server* application, which is necessary to host multiplayer servers. Although some server hosts may prefer to :ref:`download this tool through SteamCMD ` instead. .. _doc_getting_started:installing_unity: Installing Unity ---------------- Installing the Unity Editor is required for exporting custom content for the game. We recommend using the same version as *Unturned*, which currently uses version **2022.3.62f3**. Unity can be `downloaded from their website `_. Although most 2022.3 LTS versions should be compatible, and some older LTS versions *can* be used with some additional setup, those versions might not function as intended. When installing a Unity version, you will have the option to install some optional modules. You should at least install: - **Linux Build Support (Mono)** – Adds support for your mod on Linux devices. - **Mac Build Support (Mono)** – Adds support for your mod on macOS devices. Once Unity is installed, a project can be created to house custom content. At this point, it is recommended to import Unturned's provided Unity packages. Unity Packages -------------- Unturned provides multiple Unity packages with the base installation of the game. These packages include examples that can be referenced when creating custom content, and provide the tools necessary to export content from Unity. These Unity packages are located in the ``.../Unturned/Extras/Sources`` directory, and are regularly updated alongside any major updates to the game. #. Open your Unity project. #. Select **Assets > Import Package > Custom Package...** from the toolbar. #. In the file browser, navigate to the ``.../Unturned/Extras/Sources`` directory. #. Import the ``Project.unitypackage`` file; importing the ``ExampleAssets.unitypackage`` file is optional. When importing a Unity package, all of the items in the package will be installed by default. You may deselect any items that you do not want to import. Project.unitypackage ```````````````````` This package contains the bare-bones required to export custom content: - Default Project Settings - :ref:`Asset Bundling Tools ` - :ref:`Mod Hooks ` (optional) ExampleAssets.unitypackage `````````````````````````` This package contains vanilla content examples, and several useful prefabs: - ``CoreMasterBundle`` directory has an example of each type of vanilla asset. - ``Game/Sources/Animations`` directory has all of the vanilla item animations. - ``Resources/Characters/Preview.prefab`` is helpful for previewing clothes. .. warning:: Custom content should not be placed into the CoreMasterBundle directory. Instead, create a separate directory to house your custom content. Other Tools ----------- Modders will need a few more tools on hand to create custom content. Text editors ```````````` A text editor (e.g., Notepad) or a code editor (e.g., Notepad++ or Visual Studio Code) is required to write the game data files used by assets. Code editors often include other useful tools, such as being able to search-and-replace content across multiple files at once. We *do not* recommend using a word processor (e.g., Microsoft Word, LibreOffice, or WordPad). Such programs are not intended intended for writing plain text files, and it is easy to accidentally add unwanted characters when not used properly. If you are unsure what you should use, Notepad comes installed on all Windows systems by default, and lacks any additional tools or features that (while helpful) may be confusing for an inexperienced user. Image editing software `````````````````````` To create custom textures for your modded content – such as for new shirts or pants, materials for custom objects, or 2D effects – you will need an image editing software that supports transparency. Some free image editors include Paint.NET, GIMP, and Krita. Blender ``````` A 3D modeling tool such as Blender is required to create custom models (and animations). Blender is the same tool we use for *Unturned*, although it is not strictly required. ================================================ FILE: about/launch-options.rst ================================================ .. _doc_launch_options: Launch Options ============== **Launch options** can be added to *Unturned* to change certain game settings before running the game. This allows for recovering from certain problems (such as an unwanted resolution or UI scale), troubleshooting a wide range of issues, or toggling settings not available from in-game. This article lists the launch options available for *Unturned*. You can `add launch options `_ through your Steam Library. #. Right-click **Unturned** in your Steam Library. #. Select the **Properties...** button. #. On the **General** tab, find the **Launch Options** field near the bottom. #. Type options separated by spaces. For example, ``-TimeOverlay -Width=1920 -Height=1080`` will enable the TimeOverlay flag, set Width to 1920, and set Height to 1080. Game Options ------------ Some of the launch options are primarily intended for use with the Unturned Dedicated Server tool. **+connect**: Connect to a server, in the format of ``+connect :``. **-Cinematic**: Turns off many level-of-detail optimizations. This has a significant performance cost. Effects include: - 4 km draw distance and sun shadow range. - LOD groups always show their highest quality. (High LOD bias.) - Lights are always visible. (Turns off light LODs.) - Objects and resources are always visible. (No landmarks or culling volumes.) - Terrains always use splatmap shaders. (No basemap fallback texture.) - Terrains always use max-quality heightmaps. (No mesh simplification.) - Sun shadowmaps use GPU max supported resolution. (16,384 x 16,384 on some modern GPUs.) - Planar reflections render at 100% resolution. (Rather than 50%.) **-DisableCullingVolumes**: Disable object culling distance overrides. Please refer to :ref:`Manual Object Culling ` for more details. **-DisableLightLODs**: Disable fadeout of dynamic lights. Could be useful for high-quality screenshots. **-EnableCharacterControllerOverlapRecovery**: When enabled, ``CharacterControllerExtension.CheckedMove`` passes through to ``CharacterController.Move``, and ``CharacterController.enableOverlapRecovery = true``. Using this can improve performance – which can be useful for servers – but it makes out-of-bounds exploits much easier. This can cause more problems than it solves so it's not enabled by default. **-EnableWheeledVehicleGizmos**: Draw locally driven vehicle's wheel torque, RPM, slip, expected RPM, etc. **-FullscreenMode=**: Window mode override. **-FallbackGizmos**: Use 3D Unity line renderer component for debug visualization rather than pixel-perfect lines. Performance with these is lower than the default, so only intended for cases where the default is unimplemented. **-FarClipDistance** *float*: [16.0, 2048.0] overrides the maximum draw distance in the graphics menu. By default the lowest max draw distance is 614.4 meters which is slightly higher than the network distance of 512.0 meters. Useful for players who are willing to gain performance at a significant gameplay disadvantage. **-ForceTrustClient**: Disables movement validation (e.g., position difference between ticks matches speed) for vehicles. Using this is not recommended! It is easier for cheaters to fly cars with movement limits disabled. This flag should eventually be removed when(/if) vehicle movement is made server authoritative. **-FrameRateLimit=** *int*: Overrides the frame rate limit specified in the display menu. Negative values disable the limit. Useful if game is running at thousands of FPS on the loading screen and overheats. **-GameSense**: GameSense integration. **-Glazier=** *enum* (``IMGUI``, ``UIToolkit``): Use a different UI system instead of the default uGUI. Accepted values are ``IMGUI`` (legacy) and ``UIToolkit`` (experimental). For more information, refer to: :ref:`doc_glazier`. **-h** *int*: Alias of ``-height``. **-height** *int*: Override in-game resolution height. **-Holiday=** *enum* (``AprilFools``, ``Christmas``, ``Halloween``, ``HW``, ``PrideMonth``, ``Valentines``, ``XMAS``, ``LunarNewYear``, ``LNY``, ``UnturnedAnniversary``): Override the active holiday. **-HostPlayerLimit=** *int*: Clamps max number of players to this number. Useful for hosting providers. **-LegacyConsole**: Use the legacy console rather than the default threaded console. **-LogAssemblyResolve**: Log when the resolution of an assembly fails. Useful when working with non-Rocket plugins. **-LogBadMessages**: Log when the game ignores a network message, including from whom. This is only recommended if trying to narrow down whether a connection is trying to waste time on the game thread by potentially exploiting something. By default the server automatically disconnects clients that are sending invalid messages, whereas the instances logged by this option could potentially be false positives. **-LogBallisticDropConversion**: Log automatic change of older gun assets' Ballistic_Drop property to Bullet_Gravity_Multiplier. Useful when manually updating older guns to the new property. **-LogGunSpreadConversion**: Log automatic change of older gun assets' Spread_Hip property to Spread_Angle_Degrees. Useful when manually updating older guns to the new property. **-LogLevelBatchingTextureAtlasExclusions**: Please refer to :ref:`Level Batching ` for more details. **-LogSpawnTablesAfterLoadingLevel**: Log all spawn chances. **-LogVehicleWheelConfigurations**: Log automatic creation of vehicle asset's ``WheelConfigurations`` property for older vehicles. Useful when converting vehicles to the new format. **-ModulesPath** *string*: If set, search for ``.dll`` and ``.module`` files in this directory instead of in ``Unturned/Modules``. **-NetTransport=** *enum* (``SteamNetworking``, ``SteamNetworkingSockets``): SteamNetworkingSockets was used to enable the `ISteamNetworkingSockets `_ networking API, but this has since become default. SteamNetworking can be used to revert to the older, deprecated `ISteamNetworking `_ networking API. **-NoDefaultLog**: Disables log file creation unless a plugin calls setLogFilePath. **-NoDeferAssets**: Disable the deferring of loading vehicles and level objects until map load time, and instead load on startup. **-NoPreserveMissingObjects**: By default, the level editor keeps objects and foliage whose assets are missing. If this option is enabled, any missing assets are deleted instead. **-NoSteamTextFiltering**: Disable Steam text filter, and instead revert to the old naïve filter. **-NoWorkshopSubscriptions**: Disable loading of all Steam Workshop subscriptions. This can be helpful when troubleshooting issues. **-OfflineOnly**: Disables requests to the internet. For LAN servers, it skips the Steam backend connection and uses locally-cached Workshop items. **-ParseAssetMetadata**: Enables parsing asset file metadata like comments and line numbers. Useful for development (e.g., error messages) at the cost of slower loading and increased memory usage. Plugin developers building on this feature may be interested in :ref:`doc_dat_editing_code`. **-PreviewLevelBatchingTextureAtlas**: Please refer to :ref:`Level Batching ` for more details. **-PreviewLevelBatchingUniqueMaterials**: Please refer to :ref:`Level Batching ` for more details. **-RazerChroma**: Enable Razer Chroma integration on compatible devices. **-RefreshRate=**: Monitor refresh rate override. .. _doc_launch_options:resaveassets: **-ResaveAssets**: Danger! Only use this if you have a backup of your custom assets, ideally in version control. Here be dragons: Depends on the **-ParseAssetMetadata** launch option also being enabled. This is our first experiment with automatically patching asset files. It will attempt to preserve comments and line numbers in your files (this is why asset metadata is needed). However, certain comments may not be preserved. In particular, comments with blank lines surrounding them. At the time of writing (2025-05-06) the game will convert blueprints from the legacy (Blueprint_*** prefix) format to newer list-based format. It cannot yet auto-convert blueprints with NPC conditions or rewards because we haven't written conversion code for those yet, but it's on our wishlist. **-ResetSteamStatsAndAchievements**: Reset all progress on Steam achievements and stats. **-SkipAssets**: Disable loading asset bundles and Workshop content. This is useful for quickly iterating on serverside code. **-ScrollViewSensitivity** *float*: Multiplier for uGUI scroll view distance travelled when rolling the mouse wheel. **-TimeOverlay**: Show seconds since startup under FPS in the upper-left corner. **-ui_scale**: UI scale override. A common usage is to set UI scale back to its default scaling, with ``-ui_scale 1``. **-UnlockSteamAchievements**: Unlocks all Steam achievements. This is intended for achievement hunters who've moved on from the game but want to maintain their previous 100% completion status. **-UnredactedLogs**: By default, player IPs in BattlEye's logging and the public IP for Workshop downloads are redacted. This option turns that off. **-UseLevelBatching** *bool*: Overrides whether level batching can be enabled. Per-level support for level batching is still required. For example ``-UseLevelBatching=false`` disables it. Please refer to :ref:`Level Batching ` for more details. **-ValidateAssets**: Perform :ref:`additional health checks ` on assets during start-up. **-ValidateLevelBatchingUVs**: Please refer to :ref:`Level Batching ` for more details. **-w** *int*: Alias of ``-width``. **-width** *int*: Override in-game resolution width. Unity Options ------------- Unity's built-in command-line arguments take priority over *Unturned*'s equivalents. Some of the more relevant Unity arguments are mentioned below, but the rest can be found in the `Unity User Manual `_. **-batchmode**: Run in batch mode. **-force-glcore**: Force OpenGL. **-force-vulkan**: Force Vulkan. **-nographics**: Do not initialize the graphics device when running in batch mode. ================================================ FILE: about/steam-workshop.rst ================================================ .. _doc_steam_workshop: Steam Workshop ============== The **Steam Workshop** allows for sharing user-generated content (such as new maps, items, localizations, and other in-game content). This type of content is typically known as a *mod*, or *modification*. Players can download mods by clicking the Subscribe button on the detail page for the item. Players can start exploring the Steam Workshop from its `Home page `_, or learn more about the features utilized by *Unturned* from the `About page `_. Browsing -------- There are several tabs and additional filters in the Steam Workshop, to help players find the type of user-generated content they are interested in. Content under the `Mods `_ tab can be downloaded by clicking the "Subscribe" button. This content will then be available the next time you launch the game. Some mods may conflict with each other, or may not be compatible with the latest version of the game. We recommend reading the description for each mod you are interested in, in case the mod author has included helpful information. Content under the `Stockpile Submissions `_ tab cannot be downloaded. Instead, we may incorporate some of these submissions—such as new skins or cosmetics—into the actual game. Players can vote on whether they would like to see a specific submission added into the game. Accepted items may be made available for purchase, or otherwise be unlockable within the game. The `Collections `_ tab contains groups of mods, which can be quickly and easily downloaded together. These are sometimes referred to as *modpacks*. For example, you may find a collection that adds several medieval-themed mods that are all compatible with each other. Creating Mods ------------- Refer to ":ref:`doc_getting_started`" for more information about what tools are needed to create mods. Afterwards, documentation for individual types of content can be found later on in the documentation. Publishing Mods --------------- When you are ready to publish your mod, launch the game and navigate to Workshop tab of the main menu. Click the "Submit" button to begin the submission process. You will see the following fields when attempting to publish a mod: #. | **Name** – This will be displayed in the Steam Workshop, and some other locations, as the name of your mod. #. | **Collection Path** – Specify a valid file path to a folder containing your mod. For example, to upload a map you would copy your map's folder into a new folder, and then provide the path to that new folder in this field. #. | **Preview Image** – Specify a valid path to a .PNG or .JPG file, which will be used as the preview image for your mod. This is displayed in the Steam Workshop, and some other locations. #. | **Change Note** – This is an optional field. When a change note is included, that text will be added to the "Change Notes" tab of your mod's Workshop page. We recommend using this field when updating your mod. #. | **Asset Type** – Choose what type of mod you are uploading. Players will be able to filter for your mod based on its asset type. Some options have "sub-types", such as the specific item a skin is intended for. #. | **Visibility** – This defines who can view your mod once it has been published. You will usually set this to "Public", so that other players can see and download your mod. Although the other options can be helpful if you want to make a few changes before making the mod public. #. | **Allowed IPs** – This is an optional field. By including an IP address in this field, only the servers with that IP address will be able to automatically download and update the mod via the WorkshopDownloadConfig.json file available to dedicated servers. It is unlikely that you will want to use this field. #. | **Workshop Section** – Choose which section this mod should be published under. "Ready-to-Use" should be used for mods that other players can immediately download and enjoy. "Curated" should be used for skins or cosmetics that other players can vote on, and we may choose to incorporate into the game. Before you can publish any mods, you must have accepted the `Steam Subscriber Agreement and Supplemental Workshop Terms `_. If you have agreed to those terms, you will now be able to click the "Create" button and publish your mod. Updating Mods ------------- Mods can be updated from the same interface used for publishing mods. Fill in the fields similar to before. We recommend including information about your update in the "Change Note" field. Note that the "Name" and "Preview Image" fields can be left blank while updating, which will leave them unchanged. Once the fields have been filled out, select an existing upload from the list of your published mods at the bottom. Your mod will begin updating. ================================================ FILE: assets/airdrop-asset.rst ================================================ .. _doc_assets_airdrop: Airdrop Assets ============== Overrides the care package model seen falling from the dropship, as well as the barricade spawned when it lands on the ground. Referenced by the :ref:`Level Asset `. **Type** *string*: ``SDG.Unturned.AirdropAsset`` **Landed_Barricade** :ref:`Asset Pointer `: Barricade item storage asset. Pivot point of the spawned barricade matches the pivot point of the care package as it hit the ground. **Carepackage_Prefab** :ref:`Master Bundle Pointer `: Model to spawn falling. ================================================ FILE: assets/animal-asset.rst ================================================ .. _doc_assets_animal: Animal Assets ============= **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Animal``) **ID** *uint16*: Must be a unique identifier. Animal Properties ----------------- **Health** *uint16*: Total health value. **Regen** *float*: How often health should be regenerated, in seconds. After the specified amount of time passes, the animal regains 1 health. Defaults to 10 seconds. **Damage** *byte*: Damage dealt to the player per attack. **Behaviour** *enum* (``Defense``, ``Offense``, ``Ignore``): AI behavior type. Defense AI will run away when alerted, Offense AI will attack when alerted, and Ignore AI will run away when attacked. **Speed_Run** *float*: Running speed in m/s. **Speed_Walk** *float*: Walking speed in m/s. **Horizontal\_Attack\_Range** *float*: Maximum attack range on the horizontal plane. Defaults to 2.25 meters. **Horizontal\_Vehicle\_Attack\_Range** *float*: Maximum attack range on the horizontal plane, when the target is inside a vehicle. Defaults to 4.4 meters squared. **Vertical\_Attack\_Range** *float*: Maximum vertical attack range. Defaults to 2 meters. **Attack\_Interval** *float*: Minimum seconds between attacks. Defaults to one second. If the attack duration is longer than the attack interval then the attack duration is used instead. **Roars** *int*: Total number of roar sounds in Unity. A roar sound is played when the animal attacks. **Panics** *int*: Total number of panic sounds in Unity. A panic sound is played when the animal is startled. **Should_Prevent_Move_During_Startle** *bool*: If true, animal won't start moving until startle animation finishes. Defaults to false. **Attack\_Anim\_Variants** *int*: Total number of attack animations in Unity. Defaults to 1. **Eat\_Anim\_Variants** *int*: Total number of eat animations in Unity. Defaults to 1. **Glance\_Anim\_Variants** *int*: Total number of glance animations in Unity. Defaults to 2. **Startle\_Anim\_Variants** *int*: Total number of startle animations in Unity. Defaults to 1. **Should\_Play\_Anims\_On\_Dedicated\_Server** *bool*: If animations are needed on the server, such as due to having complicated triggers tied to the attack animations. Defaults to false. Drops ----- **Reward_ID** *uint16*: ID of the item spawn table to use. **Reward_XP** *uint*: Amount of experience to reward. **Reward_Min** *byte*: Minimum amount of item drops to reward. Defaults to 3. **Reward_Max** *byte*: Maximum amount of item drops to reward. Defaults to 4. **Meat** *uint16*: ID of item to spawn when animal is killed. Deprecated in favor of Reward_ID. **Pelt** *uint16*: ID of item to spawn when animal is killed. Deprecated in favor of Reward_ID. Localization ------------ **Name** *string*: Animal name in user interfaces. ================================================ FILE: assets/animation.rst ================================================ .. _doc_assets_animation: Animation ========= Unturned's character rig is terrible – so using existing animations is recommended for your sanity. Export ------ 1. Ensure scene unit system is metric with unit scale set to 1.0 and length set to meters. 2. Select the Skeleton node. 3. File > Export > FBX 4. Selected Objects: True 5. Apply Scale: FBX Units Scale 6. Add Leaf Bones: False 7. Primary Bone Axis: +X 8. Secondary Bone Axis: -Y Note that the Item.prefab from Unity is attached to the left or right hook with a local rotation of (0, 0, 90). ================================================ FILE: assets/asset-bundle-custom-data.rst ================================================ .. _doc_asset_bundle_custom_data: Asset Bundle Custom Data ======================== Unity ``ScriptableObject`` which can optionally be created in a :ref:`Master Bundle's ` root for Unturned-specific asset bundle metadata. ``Owner Workshop File Id`` *uint64*: ID of a file published to the Steam Workshop. If Unturned is loading this asset bundle from a Steam workshop file but the file ID does not match then loading will be canceled. Prevents the asset bundle from being easily copied/stolen. How to Set Owner Workshop File ------------------------------ 1. Within the Unity project window find your master bundle's root folder. This is the same as the Asset_Prefix specified in your MasterBundle.dat file. For example Hawaii's root folder is Assets/HawaiiMasterBundle. 2. Create the ``AssetBundleCustomData`` object by Right Clicking > Create > Unturned > Asset Bundle Custom Data 3. Find your workshop file's ID. This is the number after ``https://steamcommunity.com/sharedfiles/filedetails/?id=`` in the URL of your workshop file's page. 4. Set ``Owner Workshop File Id`` to match your workshop file's ID. 5. (optional) Check that Unturned is finding the custom data by looking for "Loaded (your asset bundle name) custom data from (path)" in the log file, or "Tried loading (your asset bundle name) optional custom data from (path)" in the case it is not found. ================================================ FILE: assets/asset-bundles.rst ================================================ .. _doc_asset_bundles: Asset Bundles ============= The game loads textures, audio, meshes, prefabs, etc. from **Unity Asset Bundles** at runtime. How these are setup and used has evolved over the years from individual \*.unity3d bundles to \*.content bundles to \*.masterbundle files. :ref:`Master bundles ` should be used for essentially all new projects. Tool Setup ---------- Prior to using any of these tools they must be imported into a Unity project #. Inside Unity open the Assets > Import Package > Custom Package... wizard. #. Find the Unturned installation directory. #. Navigate to the Extras/Sources directory. #. Import the Project.unitypackage. .. _doc_asset_bundles:master_bundles: Master Bundles -------------- Master bundles are the most efficient way for your assets to be packaged and distributed. They should be used for essentially any project that you plan to share with other players. There are only a few asset types that are unsupported by master bundles. File Setup `````````` Master bundles can be loaded from any directory the game loads \*.dat files from. Unless an override is specified, the nearest master bundle in the file hierarchy is used. While loading each directory is checked for a MasterBundle.dat file signalling the presence of a master bundle. For example, refer to the core.masterbundle in the Bundles directory. MasterBundle.dat can set the following keys: .. code-block:: unturneddat // Name of asset bundle file in the same directory as MasterBundle.dat. Asset_Bundle_Name core.masterbundle // Path to the asset bundle within Unity. // Unity subfolders should match 1:1 with dat subfolders. Asset_Prefix Assets/CoreMasterBundle // Version 3 is Unity 2018.4 LTS. Older versions have shader consolidation enabled for backwards compatibility. Asset_Bundle_Version 3 Individual asset \*.dats can set the following keys: .. code-block:: unturneddat // Name of master bundle to load files from. Master_Bundle_Override core.masterbundle // If included, look for an individual *.unity3d asset bundle instead. Exclude_From_Master_Bundle // Path within master bundle to load files from. // Used by notes to share a common object prefab. Bundle_Override_Path /Objects/Medium/Furniture/Note // If true, path within master bundle appends asset file name as subdirectory. // For example: // Guns/Eaglefire.asset → Guns/Eaglefire/Item.prefab Bundle_Path_Include_Filename true Tool Usage `````````` 1. Follow *Tool Setup* instructions. 2. Open the tool from the Window > Unturned > Master Bundle Tool menu. 3. Select directories of assets in the Project window. 4. In the Inspector window tag them in any asset bundle. 5. Click the checkbox next to an asset bundle's name in the tool to mark it as a master bundle. This filters the list of asset bundles to show, and tracks an export path associated with it. 6. Click the ... to choose a destination for the bundle file. 7. Click Export. 8. (optional) When redistributing the asset bundle the "multiplatform" toggle should be enabled. This ensures the appropriate shaders for each platform are included, and exports a ".hash" file so the server can validate client asset bundle integrity. Motivations ``````````` When upgrading to Unity 2017.4 LTS it became apparent that all asset bundles would have to be re-exported from Unity due to shader compatibility changes. This would be an incredible amount of files, so it was time to re-approach the \*.content issue in a way that could quickly convert all existing content. This was handled by keeping the file hierarchy 1:1 and guessing the file extension for the by-name loading. Individual Asset Bundles ------------------------ Most official files have transitioned to the master bundle system, but some use individual asset bundles (\*.unity3d). For example: - Per-map road textures. - Colors used by charts. - Level ambience. Tool Usage `````````` 1. Follow *Tool Setup* instructions. 2. Open the tool from the Window > Unturned > Bundle Tool menu. 3. Select individual assets or directories of assets in the Project window. 4. Click Grab to preview which assets will be exported. 5. Click Bundle to choose a destination for the asset bundle file. Motivations ``````````` When beginning development of 3.0, it was key to support runtime loading of custom modded content. At the time files in asset bundles were loaded by name without extension, so each game type looked for specific names like "Item", "Object", "Animal", etc. The .unity3d extension was chosen for web browser compatibility. Obviously this system did not age well. Content Bundles (\*.content) ---------------------------- .. deprecated:: 3.22.4.0 This format was historically used by terrain, material palettes, and radio songs. After the April 23, 2021 patch (version 3.21.15.0) these assets can all use master bundles instead. As of the February 25, 2022 patch (version 3.22.4.0) any remaining support for content bundles has been removed. New references should use a master bundle name and relative path for the "Name" and "Path" properties. Reusing Content Bundles ``````````````````````` Although it is preferable to properly migrate older assets into master bundles, preexisting content bundles can be easily reused as a master bundle. Rename the \*.content file to be \*.masterbundle file instead. Then, add a corresponding MasterBundle.dat file as described in the file setup for master bundles. ================================================ FILE: assets/asset-definitions.rst ================================================ .. _doc_asset_definitions: Asset Definitions ================= Unturned **asset definitions** associate game data with Unity asset bundles. They are stored in ``.dat`` or ``.asset`` files. For information about the file format please refer to :ref:`Data File Format `. Header ------ Each asset has a common ``GUID`` and ``Type`` header: **GUID** :ref:`GUID `: Unique ID used to link assets together. If left empty the game will prepend a newly generated GUID during startup. **Type** *string*: Specific guides will list individual type names. This determines which keys the game will read. It can also be set to the fully qualified name of any class in any module. .. note:: ``Type`` and ``GUID`` can either be specified in the root dictionary (default), or in a ``Metadata`` sub-dictionary. For example this is valid as well: .. code-block:: text Metadata { GUID 7e4b847061b64272b42ea8869fd053c7 Type SDG.Unturned.Asset } If ``GUID`` is specified in the ``Metadata`` sub-dictionary the game cannot (as of 2023-04-13) automatically prepend a newly generated one during startup. Body ---- The body contains any class properties. Individual asset type documentation elaborates on these. **ID** *uint16*: 16-bit identifier. Unfortunately this ID must be unique within each category of assets (vehicles, items, animals, etc). Objects are the exception from this legacy restriction because they have been upgraded to fully use GUIDs. Optionally the body properties can be placed into an ``Asset`` sub-dictionary. For example: .. code-block:: text GUID [...] Type [...] Asset { ID [...] Key1 Value Key2 Value } Is equivalent to: .. code-block:: text GUID [...] Type [...] ID [...] Key1 Value Key2 Value Unity Asset Bundles ------------------- Each Unturned asset is associated with a Unity asset bundle. If there is a master bundle in the file hierarchy that takes priority, otherwise a ``.unity3d`` bundle with the same name as the ``.dat`` file is used. There are several keys available to control the asset bundle: **Asset_Bundle_Version** *int*: Indicates which version of Unity this ``.unity3d`` bundle was built for. When Unturned upgrades Unity versions it tries to maintain backwards compatibility based on this number. ``1`` is Unity 5.5, ``2`` is 2017.4 LTS, and ``3`` is 2018 LTS and 2019 LTS, ``4`` is 2020 LTS, ``5`` is 2021 LTS, and ``6`` is latest (Unity 2022 LTS). **Master_Bundle_Override** *string*: Name of a master bundle to use rather than the ``.unity3d`` bundle or master bundle found in the hierarchy. **Exclude_From_Master_Bundle** *string*: If this key exists the asset will look for a ``.unity3d`` bundle instead of the hierarchy. **Bundle_Override_Path** *string*: Path within the master bundle to load rather than this asset's file path. Localization ------------ Each asset looks for a localization ``.dat`` file in the same directory based on the current language. For example: ``English.dat`` or ``French.dat``. Loading Order ------------- When scanning a folder for assets the game checks in this order: 1. Is there a ``.asset`` file with the same name as the folder? e.g. Eaglefire.asset in the Eaglefire folder 2. Is there a ``.dat`` file with the same name as the folder? e.g. Eaglefire.dat in the Eaglefire folder 3. Is there an ``Asset.dat`` file? 4. Otherwise, load all files with the ``.asset`` extension in the folder. ================================================ FILE: assets/asset-validation.rst ================================================ .. _doc_asset_validation: Asset Validation ================ During startup the game runs fast basic health checks on assets while loading, but there are a variety of slower tests available. These can be enabled with the ``-ValidateAssets`` command-line flag. Errors are logged to the Client.log file, as well as to the Asset Errors menu. **Navmesh Readable**: Object navmeshes should have the CPU Readable flag enabled in Unity. This is required for Recast to be able to generate the level navmesh. **Mesh Readable**: Most non-navmesh meshes do not need to have the CPU Readable flag enabled in Unity. This is not currently enforced however, as the core content has lots of cases which still need cleaning up. **Missing Meshes**: Mesh filters without a mesh, or mesh renderers without a mesh filter are found and logged. **Mesh Vertex Counts**: Meshes with unusually high numbers of vertices are recommended to be optimized. Typically this is simply a matter of removing unused faces and vertices. Colliders have a lower recommended target because collision against complex meshes is slower than rendering complex meshes. **Missing Materials**: Renderers without materials are found and logged. One exception to this is "DepthMask" renderers which are set by the game. **Material Counts**: Renderers with high numbers of materials are recommended to be merged and simplified. Each individual material needs to be rendered separately (usually), so less materials is better. Good practice is to have one material for each render type on an object, i.e. a material for the opaque surfaces and a material for the transparent surfaces (if any). **Texture Readable**: Most textures do not need to have the CPU Readable flag enabled in Unity. Disabling means a copy is not kept in RAM. One exception is shirt and pants textures which are layered on the CPU. **Texture NPOT**: Most textures should have power-of-two dimensions, e.g. 1 x 2, 4 x 4, 64 x 32, etc. GPUs are best equipped for drawing these resolutions. Unity has import options for scaling up or down to the nearest power of two. **Audio Samples**: Long audio clips with high frequencies are found and logged. Generally the clips are fairly small files. ================================================ FILE: assets/character-mesh-replacement.rst ================================================ .. _doc_character_mesh_replacement: Character Mesh Replacement ========================== The player's character mesh can be entirely replaced with a special :ref:`shirt item `. There's an example CharacterMeshReplacementTest item (ID 1522), as well as example source files in the ExampleAssets.unitypackage under the Shirts directory. Two limitations are that it must be a shirt because only shirts are loaded for first person (1P) views, and the 1P model should only contain the arms because the rest of the body is not animated. Properties Reference -------------------- * **Has_1P_Character_Mesh_Override**: true * **Character_Mesh_3P_Override_LODs**: >0 * **Has_Character_Material_Override**: true * **Hair_Visible**: true/false * **Beard_Visible**: true/false If ``Has_1P_Character_Mesh_Override`` is true then the game will try to load a prefab named "Character_Mesh_1P_Override_0". This should have a MeshFilter component with the first person arms replacement mesh. If ``Character_Mesh_3P_Override_LODs`` is greater than zero then the game will try to load prefabs for each LOD index (e.g., Character_Mesh_3P_Override_0). These should have MeshFilter components for the third person replacement meshes. If ``Has_Character_Material_Override`` is true then the game will try to load a material named "Character_Material_Override" to replace the 1P and 3P mesh materials. Without this, equipped shirt and pants textures will be used by default. ================================================ FILE: assets/crafting-asset.rst ================================================ .. _doc_assets_crafting: Crafting Assets =============== This asset defines blueprints outside of an item asset. This may be useful for organizational purposes or blueprints without a clear "owner" item. For example, if a blueprint has multiple inputs and outputs it might not make sense to include in a specific item asset. **GUID** *32-digit hexadecimal*: Refer to :ref:`doc_data_guid` documentation. **Type** ``SDG.Unturned.CraftingAsset`` Properties ---------- The same :ref:`Blueprints ` property as items. However, only the V2 blueprints format is supported here. ================================================ FILE: assets/crafting-blacklist-asset.rst ================================================ .. _doc_assets_crafting_blacklist: Crafting Blacklist Assets ========================= Prevents specific items or blueprints from being used while crafting. They are hidden from the item quick actions menu and recipe list. **Type** *string*: ``SDG.Unturned.CraftingBlacklistAsset`` **Input_Items** array of Item :ref:`Asset Pointers `: Any blueprints consuming these items cannot be crafted. For example (blacklisted items are highlighted): .. code-block:: unturnedasset :linenos: :emphasize-lines: 4, 7-10, 13-16 Input_Items [ // Orange Hoodie "GUID" "67c76cdf16024bf68b6e5d14d4c617ab" // Individual items can also be enclosed in brackets { } { // Eaglefire GUID b03d581a5c1a490f995f8deba57b0f17 } // Jeans dab78cc4d66645bfb8169be7c15cf876 55c69817a31448b685c7f788ec7d2d0c bdae9d26ca704d729b2b0f34812d2a36 67a6ec52e4b24ffd89f75ceee0eb5179 ] **Output_Items** array of Item :ref:`Asset Pointers `: Any blueprints generating these items cannot be crafted. **Blueprints** array: Prevent specific individual blueprints from being crafted. Each entry has an ``Item`` :ref:`Asset Pointer ` and one of ``BlueprintName`` string or ``Blueprint`` index. For example, to prevent the Chef Hat from being salvaged: .. code-block:: unturnedasset Blueprints [ { Item a6099002318e4d58b8e59d431bcf1b8a BlueprintName Salvage } ] .. note:: ``BlueprintName`` should be used instead of ``Blueprint`` (index) where possible because the index may change if the item's Blueprints list is reorganized. This requires specifying a ``Name`` in the blueprint, however. **Allow_Core_Blueprints** *bool*: Defaults to ``true``. If ``false``, blueprints from the vanilla/built-in items are not allowed. ================================================ FILE: assets/curated-items.rst ================================================ .. _doc_curated_items: Curated Items ============= Community-created items (such as skins and cosmetics) can be submitted to the :ref:`doc_steam_workshop` for consideration to be incorporated into the actual game. These items can be found under the `Stockpile Submissions `_ tab, where other players can vote on whether they would like to see a specific submission added into the game. Accepted items may be made available for purchase, or otherwise be unlockable within the game. Most accepted items are sold in the `Stockpile `_ (also known as the item store). The default revenue share is 25%, but for items associated with maps (e.g., the `Elver Map Bundle `_) the revenue share is 50%. Your own split of that revenue share may be lower when an item has multiple contributors – such as when your item was created by multiple people, or if your item is added as part of bundle that contains many different peoples' items. Requirements ------------ For the tools necessary to start creating skins or cosmetics, refer to the :ref:`doc_getting_started` page. Some additional preparation is needed compared to creating mods: #. Follow the submission guidelines. #. Organize your Unity project. #. Create your cosmetic or skin. #. Specify a Mythical effect placement (if your item is a cosmetic). #. Export a Unity package. #. Submit your item to the :ref:`doc_steam_workshop`. Guidelines ---------- .. |ico1| image:: /img/1e1e1e.png :width: 15px .. |ico2| image:: /img/f0f0f0.png :width: 15px Most of these guidelines are intended to help promote consistency with *Unturned*'s art style. Here are the guidelines you should keep in mind: #. | Avoid high contrast colors. They're often painful to look at, especially when the item appears in harsh lighting. #. | Do not go darker than |ico1| #1e1e1e or brighter than |ico2| #f0f0f0. Both extremes of brightness (and fully saturated colors) don't play nicely with the game's lighting. Most official content uses medium-intensity colors. #. | Edges of clothing should have a slightly darker border that is one pixel wide. This can be easily seen on official clothing items, along the cuffs and bottom hem of shirts. #. | Flat textures meant to blend into the terrain (e.g., similar to the in-game ghillie suit) should not be used. Instead, you can incorporated patterned camouflage into your items. #. | Textures should be kept to a reasonable resolution. Ideally, 2048x2048 scaled down to 1024x1024 for large items (e.g., the Maplestrike), and 1024x1024 scaled down to 512x512 for small items (e.g., the Cobra). #. | Avoid using high metallic or smoothness values. Unturned does not use reflection probes, and the only sources of metallic reflection data are limited to optional features like skybox reflections and screen-space reflections. #. | Corners of models should not be beveled. Most models have sharp edges (e.g., 90°). There is not a hard limit on vertex, triangle, or polygon count because anything matching the game's art style will naturally have a reasonable number. #. | Skins with custom models should generally respect the original item's silhouette. Be mindful that attachments (such as barrels, tacticals, sights, and grips) should still work on the custom model *and* look good. #. | Cosmetics should avoid potentially confusing players. For example: if a hat looks like hair, it should have some additional accessory or detail to help distinguish it as a cosmetic. Otherwise, it would look like the player isn't wearing any item at all. #. | Only submit content that you created yourself. Do not use copyrighted material or trademarks that you do not own or have permission to use. #. | We do not support custom shaders, i.e., shaders not included in the vanilla game cannot be used. #. | Unfortunately, physics do not play well with the Unturned character, and cannot be used on cosmetics at this time. Remember: these are just guidelines. Except in specific cases (such as copyright infringement), we may occasionally accept items that break some of these guidelines. However, these are the things we are looking for in submissions. Sticking to these guidelines will help your chances of getting your item accepted. Unity Project Organization -------------------------- Organizing your project into two separate folders: one for your exported asset-bundled files (e.g., an ``Item.prefab``) and one for your imported sources (e.g., a ``.blend`` file) is greatly appreciated. This makes it much easier for us to ensure only the necessary assets are included in the game. For reference: all of the base game's asset-bundled files are in the ``Assets/CoreMasterBundle`` folder, and all of the source files are in the ``Assets/Game/Sources`` folder. Cosmetics ````````` Some additional notes exist for organizing cosmetic items. - | Map-related cosmetics are in per-map folders, and prefixed with the map's name. For example, Arid's "`Arrowhead `_" exported files are located in ``Assets/CoreMasterBundle/Items/Arid/Arid_Arrowhead`` and the source files are in ``Assets/Game/Sources/Items/Arid``. - | Outfits have their items in a per-outfit folder, and are prefixed with the outfit name. For example, the "`Cultist's Mask `_" exported files are in a per-outfit folder and prefixed with the outfit name. For example, the Cultist bundle's mask item export files are located in ``Assets/CoreMasterBundle/Items/Outfits/Cultist/Cultist_Mask`` and the source files are in ``Assets/Game/Sources/Items/Outfits/Cultist``. - | Miscellaneous items are in the folder matching their type. For example, the "`Backpack Turtle `_" exported files are located in ``Assets/CoreMasterBundle/Items/Backpacks/Turtle_Backpack`` and the source files are in ``Assets/Game/Sources/Items/Backpacks/Turtle_Backpack``. Exporting Unity Package ----------------------- Since the assets for accepted cosmetics are included in the game's core asset bundle, a ``.unitypackage`` file is required along with the regular ``.dat`` files for items. To export the package: #. Select the folders containing your ``Item.prefab`` files (or equivalent asset-bundled files for other types of items). For example, if we were submitting our official Fedora item then we would select the ``Assets/CoreMasterBundle/Items/Hats/Fedora`` folder. #. Right-click in the **Project** window. #. Click **Export Package...**. #. Ensure **Include dependencies** is checked to include the source files that aren't directly placed in the asset bundles (i.e., the meshes, materials, textures, etc.). .. note:: The Unity package is in *addition* to the regular asset ``.dat`` and ``English.dat`` files required for items to work. Including the ``.dat`` files from your setup is useful for keeping the accepted version consistent. While not strictly necessary, including a name and description in the English text file is appreciated and will probably be used. Creating Cosmetics ------------------ In terms of setup, cosmetics are identical to actual in-game clothing items. The main difference between cosmetics and clothing is that the former does not offer any benefits to the player, appear over most worn clothing items, and can have their visibility toggled at will by the player. Since these are otherwise identical, we recommend referencing the clothing items included in the ExampleAssets.unitypackage in order to create your cosmetic items. Mythical Effect Placement ````````````````````````` .. figure:: /img/EffectTransform.png Example "Effect" transform positioning and orientation. Most cosmetic items will want to support mythical effects. You will need to add an "Effect" child transform to both the Item.prefab and the clothing prefab (i.e., Backpack.prefab, Glasses.prefab, Hat.prefab, Mask.prefab, or Vest.prefab) for your item to support this. The orientation is rather unfortunate: +Z is the mythical's up direction and +Y is the mythical's forward direction. Creating Skins -------------- Any item in *Unturned* could support skins, but not every item does at this time. We recommend only creating skins for items that are already skinnable. This includes most weapons, along with a few miscellaneous items such as Canned Beans and the Detonator. The unwrapped meshes are included as part of the ExampleAssets.unitypackage. At the very least, you will want to create a custom albedo for your skin. You can also add custom metallic or emission textures. When eventually uploading your skin to the Steam Workshop, please make sure you follow the "Exporting Unity Package" steps to include your source files! This allows us to add any extra needed assets, or fix minor issues. .. figure:: /img/FiestaAugewehrBundles.png The Fiesta Augewehr skin includes all four types of materials. Unless your skin includes a custom mesh (as detailed in a later section), your asset-bundled files will not include a prefab. Instead, skins will include the material(s) used by the item and any attachments attached to it. - | **Primary**: The ``Skin_Primary.mat`` is the material used by the skinned item itself. Every skin should have a single primary material. - | **Secondary**: Each ``Skin_Secondary_#.mat`` included in the bundle files is for a specific attachment (where the ``#`` is the attachment's legacy ID). Skins can have multiple secondary materials. When creating skins for sniper rifles, you will usually want to include at least one secondary material for a scope. - | **Attachment**: The ``Skin_Attachment.mat`` (also called the "layered attachments material") is used when a secondary material has not been provided for an attachment that has texture masks. For example, the 8x Scope has its mount and knobs masked out. - | **Tertiary**: The ``Skin_Tertiary.mat`` (also called the "fallback attachments materials") is used when none of the other included materials are applicable for an attached attachment. You will usually want to include a tertiary material if your skin has an attachments material. .. figure:: /img/FallbackLayered.png Notice how some parts of the 8x Scope retains some of its original texture when a Layered Attachments material is included, while the Fallback Attachments material completely covers it. Although most skins keep their layered (Skin_Attachment.mat) and fallback (Skin_Tertiary.mat) textures identical, this is not required. Some skins have fairly different secondary, attachment, and tertiary materials. The Bloodsport Calling Card, Bouquet Bluntforce, and Vortex Augewehr are good examples of this. Custom Models ````````````` Skins can override an item's original model with a custom one. If you create a skin that does this, it's more likely to be accepted if your custom model still respects the original silhouette of the item. By extension, things like attachments and stat counters should still look good when attached to the item. Setting this up in Unity is simple. Your asset-bundled files should include a ``Override_Mesh_#.prefab`` (where ``#`` is the LOD's index). For example, ``Override_Mesh_0.prefab``. This prefab simply includes a Mesh Filter component that is linked to your custom model. Using Collections ----------------- Collections allow for grouping multiple item submissions together, making it easier for users to discover and rate similar content when browsing the Steam Workshop. Creators often use collections to group skins that all share a similar pattern together. Some creators may create collections when they want to showcase different versions of their item (e.g., palette swaps). While these *could* be combined into a single submission, having them separate allows for players to vote on the specific version(s) they would like to see accepted into the game. Another way of using collections is to organize submissions that were designed to be used together. For example, a bunch of individual cosmetic items that would form a complete outfit. Creating a collection that contains each individual item allows players to vote on the specific item(s) they would like to see, and makes it easier for us to accept only a couple pieces from an outfit (e.g., when choosing items for a new box). You may also consider using an :ref:`OutfitAsset ` to create a preview image that can be used on the Workshop page for the outfit's collection or its related items. ================================================ FILE: assets/data-file-format.rst ================================================ .. _doc_data_file_format: Data File Format ================ This article describes the syntax of Unturned's ``.dat`` and ``.asset`` files. Each line is a key-value pair separated by a space. The key and/or value can optionally be in quotes. For example: .. code-block:: unturneddat Key1 First value "Key2 in quotes" Second value Key3 "Third value" Will be parsed as: .. code-block:: text "Key1" = "First value" "Key2 in quotes" = "Second value" "Key3" = "Third value" The only reason to quote a value is to enable comments on the same line. Quotation marks within a quoted key/value can be escaped with a ``\`` backslash. For example ``"a \"b\" c"`` is parsed with quotation marks around ``b``. Keys support quotes in case a space is required, but no keys in the vanilla game use spaces. .. note:: Keys are case-insensitive. i.e., ``Use_Cool_Option true`` and ``UsE_cOoL_oPtIoN true`` are identical. Keys should be unique within their dictionary. Acceptable values for a key will depend on their data type. Most—but not all—properties will use one of the :ref:`C# built-in types `. Objects / Dictionaries ---------------------- Each series of key-value pairs is a dictionary (sometimes called an object). The top level of the file is treated as a dictionary, and child dictionaries can be added with ``{ }`` curly braces. Adding ``{`` on the line after a key opens a dictionary, and the matching ``}`` closes it. In this example ``object1`` is a child dictionary in the root dictionary, and ``object2`` is a grand-child: .. code-block:: unturneddat object1 { object2 { key value } } Arrays / Lists -------------- Lists (sometimes called an array) can be added with ``[ ]`` square brackets. Adding ``[`` on the line after a key opens a list, and the matching ``]`` closes it. In this example ``values`` is a list of strings: .. code-block:: unturneddat values [ first value second value third value ] Lists can also contain dictionaries as seen in this example: .. code-block:: unturneddat List_Of_Objects [ { x 1 y 2 } { x 3 y 4 } ] .. note:: Many older asset properties predate the addition of lists. In these cases arrays/lists are typically handled by a key specifying the number of items, and then appending the index number to each element's key. For example: .. code-block:: unturneddat // Total number of elements in old-style list Elements 2 // First element has an index of 0 Element_0 A // Second element has an index of 1 Element_1 B Comments -------- Lines starting with ``//`` are comments, which means they are excluded from parsing. Comments can be useful for adding helpful, explanatory notes inside an asset. Comments can also be added to the end of a line if the value is quoted. For example these comments are valid: .. code-block:: unturneddat // a comment key1 value1 key2 "value2" // in-line comment Whereas this comment will not be excluded from the value: .. code-block:: unturneddat key value // this is not treated as a comment because the value is not in quotes FAQ (Frequently Asked Questions) -------------------------------- **Q. How do I write a multi-line value?** The ``\n`` escape sequence starts a new line. For example: .. code-block:: unturneddat Text First line\nSecond line Will set the value of ``Text`` to: .. code-block:: text First line Second line **Q. How do I write an in-line comment after a value containing quotation marks?** In-line comments require the value to enclosed in quotation marks, so quotation marks in the value must be escaped with ``\"``: .. code-block:: unturneddat // The parser will read the comment as part of the value because it doesn't know where the value ends. Text Why use so-called "scare quotes" instead of /s? // Comment here // The parser will exclude the comment from the value and replace the \" with quotation marks. Text "Why use so-called \"scare quotes\" instead of /s?" // Comment here **Q. Why can't I start a list or dictionary on the same line as a key?** This is—unfortunately—not supported because it would break backwards compatibility with the oldest ``.dat`` files. Older files may have ``[`` or ``{`` as the first letter of a value. As an example of the problem: .. code-block:: text SomeDictionary { SomeList [ ] } Instead, the opening ``[`` or ``{`` must be placed on the next line: .. code-block:: unturneddat SomeDictionary { SomeList [ ] } History ------- Prior to the 3.23.6.0 update there were two sets of custom Unturned syntax: "v1" for ``.dat`` files, and "v2" for ``.asset`` files. Assets using v1 syntax only supported key-value pairs, whereas v2 introduced dictionaries, lists, and required keys/values to be quoted. This is why ``{`` and ``[`` must be on a new line, as existing v1 assets may have ``{`` or ``[`` as the first character of a value. ================================================ FILE: assets/effect-asset.rst ================================================ .. _doc_assets_effect: Effect Assets ============= **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Effect``) **ID** *uint16*: Must be a unique identifier. General data ------------ **Blast** *uint16* or *GUID*: ID or GUID of effect. **Lifetime** *float*: Duration of the effect. **Lifetime_Spread** *float*: Variation on the duration of the effect. A random value is chosen between the specified spread value, and the negative of that spread value. Default is 4 seconds. **Gore** *bool*: Effect is hidden when gore is disabled. **OneShotAudio** :ref:`Master Bundle Pointer `: AudioClip or OneShotAudioDefinition to play alongside effect. Useful for audio-only effects, in which case Effect prefab is unnecessary and can be excluded. **Static** *flag*: Disable randomized audio pitch change. **Randomize_Rotation** *bool*: Rolls the effect around the hit axis. Defaults to true. **Spawn_On_Dedicated_Server** *flag*: Spawn effect on server. **Relevant_Distance** *float*: How far away players can be before an asset effect should not be sent to them, measured in meters. Players within this radius will be sent the effect in multiplayer. **Preload** *byte*: Total number of the effect to pre-instantiate in the effect pool to reduce hitching when first used. **Is_Music** *bool*: Placeholder to disable music when used in an ambiance volume if music option is disabled. Once the audio settings menu is separated out there will be a volume multiplier for music. Camera shake ------------ **CameraShake_MagnitudeDegrees** *float*: The amount of camera shake inflicted upon affected players, in degrees. **CameraShake_Radius** *float*: Players within the radius around the effect are affected by other camera shake properties. Splatters --------- **Splatter** *int*: Total number of splatter textures in Unity. **Splatters** *int*: Total number of splatters to spawn. **Splatter_Lifetime** *float*: Duration of the splatter. **Splatter_Lifetime_Spread** *float*: Variation on the duration of each individual splatter after effect spawn. A random value is chosen between the specified spread value, and the negative of that spread value. Default is 1 second. **Splatter_Liquid** *flag*: Splatters are visible regardless of effect graphics settings being disabled, and slightly changes the direction of each splatter. **Splatter_Temperature** *enum* (``Acid``, ``Burning``, ``Warm``): Temperature status effect caused when standing in the effect. **Splatter_Preload** *byte*: Total number of the splatter effects to pre-instantiate in the effect pool to reduce hitching when first used. ================================================ FILE: assets/foliage-asset.rst ================================================ .. _doc_assets_foliage: Foliage Assets ============== There are sub-types of foliage asset for different uses, most notably instanced meshes (grass, pebbles) and resources (trees). Unlike the older system, tree baking cannot be configured directly within the level editor yet, but there are two benefits to separating baking settings from the trees themselves: 1. Different biomes or levels can use the same trees with different parameters. For example a dense forest material with less dense forest surrounding it, or using tree assets from a different map with custom configuration. 2. Eventually the resource system should be converted into a regular objects (this will be automatic) but most objects do not need foliage parameters. FoliageResourceInfoAsset Properties Reference --------------------------------------------- **Type** *string*: ``SDG.Framework.Foliage.FoliageResourceInfoAsset`` **Resource** :ref:`Asset Pointer `: actual tree to spawn. **Obstruction_Radius** *float*: spawn position is invalid if a sphere with this radius overlaps anything. **Density** *float*: this value is poorly named. One tree will try to spawn per this many square meters. For example a value of 4 will spawn approximately once per 2m x 2m area. **Min_Weight** *float*: [0, 1] only spawn if landscape material weight is greater than this value. **Max_Weight** *float*: [0, 1] only spawn if landscape material weight is less than this value. **Min_Angle** *float*: [0, 90] degrees only spawn if surface angle is greater than this value. For example a boulder only spawning on slopes steeper than 45 degrees. **Max_Angle** *float*: [0, 90] degrees only spawn if surface angle is less than this value. For example a tree not growing on slopes steeper than 30 degrees. **Uniform_Scale** *bool*: If true, max and min scale are floats rather than vector3. This enables an optimization for instanced mesh foliage (like grass), packing more instances per batch. Upgrade Devkit Foliage from V1 to V2 ------------------------------------ .. note:: Maps with auto-converted terrain from the 3.22.8.0 update will have already been converted to V2. V1 of devkit foliage saved each small, individual region into their own files, which made maps slow to copy, download, and install. V2 fixes this by storing pointers for each region into a single file, at the cost of RAM in the map editor. Following the 3.22.20.0 update, maps using v1 foliage will automatically update to v2 the next time they are saved, without needing to use the ``-SaveFoliageUsingV2`` command-line argument. The older v1 foliage files are still kept in the map's Foliage directory as a backup. These v1 files can be manually removed after having converted to v2, in order to free up space. ================================================ FILE: assets/layers.rst ================================================ .. _doc_assets_layers: Layers ====== Upfront: obviously Unturned makes poor use of Unity's Layers. This document exists as much for my personal reference as yours. My only defense is that these layers are entrenched from the earliest versions back in 2013, when I was 15 or 16. Overview -------- Built-in Layers - **0 Default** - **1 TransparentFX** - **2 Ignore Raycast** - **4 Water**: ocean and water tiles. - **5 UI**: menus with :ref:`uGUI glazier ` as well as plugin custom menus. User Layers - **8 Logic**: Clickable overlays like the position, rotation and scale handles. Editor debug visuals that can be seen through walls are on this layer. - **9 Player**: Character capsule (not body hitboxes). Exists for all players server-side, but only the local player client-side. - **10 Enemy**: Player body hitboxes. - **11 Viewmodel**: Local first-person arms and weapon. - **12 Debris**: Typically small simulated objects like ragdolls, grenades, falling tree trunks, destroyed structures, and fragmented objects. - **13 Item**: Dropped interactable items. - **14 Resource**: Trees and boulders. Barricades attached to vehicles are moved to this layer. - **15 Large**: Large props placed in the level editor. - **16 Medium**: Medium props placed in the level editor. - **17 Small**: Small props without collision placed in the level editor. - **18 Sky**: Distant effects without collision like the clouds and stars. - **19 Environment**: Roads, grass and pebbles. - **20 Ground**: Landscape / terrain. - **21 Clip**: Invisible collision. - **22 Navmesh**: Invisible zombie-only collision. Navmesh graphs are generated from this collision, but the collision is also loaded on the server to help push zombies around. - **23 Entity**: Zombie and animal body hitboxes. - **24 Agent**: Zombie and animal character capsules (not body hitboxes). - **25 Ladder**: Invisible climbable trigger. - **26 Vehicle**: All vehicle colliders. - **27 Barricade**: Barricade item placed in the world. Barricades attached to vehicles are moved to the Resource layer. - **28 Structure**: Structure item placed in the world. - **29 Tire**: Wheel colliders. Allows wheels to mask what they collide with. - **30 Trap**: Typically trigger colliders including rocket launcher projectiles and kill volumes. - **31 Ground2**: No longer used after old maps were converted to terrain tiles. Previously this was for out-of-bounds terrain. Reserved for future use. Layer Collision Matrix ---------------------- Note that these comments do **NOT** apply to collision queries like raycasts, spherecasts, etc. No physics collision: - **Default** - **TransparentFX** - **Ignore Raycast** - **Water** - **UI** - **Logic** - **Enemy** - **Viewmodel** - **Small** - **Sky** - **Environment** - **Ground** - **Entity** - **Ladder** - **Ground2** Has physics collision: - **Player**: Character controller layer is used by Unity as the underlying query mask. - **Debris** - **Item** - **Resource** - **Large** - **Medium** - **Environment** - **Ground** - **Clip**: Collides with Player and Vehicle for its original purpose. Makeshift vehicles have invisible colliders on this layer to expand their simulation size without affecting barricade placement, so Clip also collides with some of the same layers as Vehicle. - **Navmesh** - **Agent**: Character controller layer is used by Unity as the underlying query mask. - **Vehicle** - **Barricade** - **Structure** - **Tire**: Wheel collider layer is used by Unity as the underlying query mask. - **Trap** ================================================ FILE: assets/level-asset.rst ================================================ .. _doc_assets_level: Level Assets ============ Each map can be associated with a **Level Asset**. These assets contain gameplay information not necessary for the main menus. Refer to :ref:`Level Config ` for information on linking a level asset to a map. For examples, check the ``Assets/Levels`` directory. **Type** *string*: ``SDG.Unturned.LevelAsset`` **Dropship** :ref:`Master Bundle Pointer `: Overrides the model seen flying over the map when a care package is dropped. **Airdrop** :ref:`Asset Pointer `: Asset pointer to an :ref:`Airdrop Asset `. Overrides the falling care package model. **Crafting_Blacklists** array of :ref:`Asset Pointers `: Asset pointers to :ref:`Crafting Blacklist(s) `. Prevents specific items or blueprints from being used while crafting in the level. **Min_Stealth_Radius** *float*: Player stealth skill level cannot reduce minimum detection distance below this value. **Weather_Types** *array*: Determines which weather can occur naturally. Refer to schedulable weather properties. If weather is using legacy weather the default rain and snow will be included. **Perpetual_Weather_Asset** :ref:`Asset Pointer `: Asset pointer to a :ref:`Weather Asset `. Overrides weather scheduling. **Global_Weather_Mask** :ref:`u32 Mask `: Fallback weather mask while player is not inside an ambience volume. Defaults to 0xFFFFFFFF. **Skills** *array*: Overrides skill default and max levels. Refer to skill rule properties. **Skillset_Loadouts** *dictionary*: Overrides per-skillset starting items. Can be used to prevent skillset default items in singleplayer. Server "Loadout" command takes priority over this option. Please refer to Skillset Loadout properties below for more details. **TerrainColors** *array*: Specifies which colors are too similar to terrain colors. Please refer to Terrain Color Properties below. **Enable_Admin_Faster_Salvage_Duration** *bool*: By default, players in singleplayer and admins in multiplayer have a faster salvage time. **Has_Clouds** *bool*: Disables clouds in skybox when false. Defaults to true. **Loading_Screen_Music** *array*: Randomly selected. Refer to music properties. **Should_Animate_Background_Image** *bool*: If true, the background image moves left/right with loading progress. Defaults to false because maps have important information on the loading screen. **Death_Music** :ref:`Master Bundle Pointer `: Audio clip played after death. **UnderwaterFogDensity** *float*: Overrides fog effect intensity while the camera is underwater. Defaults to ``0.075``. **Allow_Building_In_Safezone_In_Singleplayer** *bool*: If true, players can bypass safezone's no-buildables mode in singleplayer. Defaults to false. **Tags** :ref:`list ` of :ref:`Asset Pointer ` to :ref:`doc_assets_tag`: Blueprints can test for these tags as an alternative to ``Map`` name check. May be extended in the future. .. _doc_assets_level:supports_fishing_volumes: **Supports_Fishing_Volumes** *bool*: If true, this level has assigned fishing spawn tables to water volumes (or set the default table). Defaults to false. **Default_Fish_Spawn_Table** :ref:`Asset Pointer `: Fishing rods using per-water-volume fishing spawn table fallback to this table. Cloud Override Properties ------------------------- When clouds are disabled (``Has_Clouds false``), these properties can be used to control a custom particle system using the cloud color and intensity from the lighting settings. .. warning:: Custom clouds are *not* recommended as they behave inconsistently at lower max draw distances. Early versions of 3.x had a very high max draw distance (~8 km). The sun, moon, clouds, and stars were 3D objects scaled almost to the edge of the far clip plane. Later versions combined these details into a skybox shader which enabled the max draw distance to be configured by players, but at the cost of reduced customization. As a workaround, mappers created 3D cloud particles attached to the camera. Distant particles were cut off at the far clip plane, but a shader with the ``ZClip False`` resolved this. Unfortunately, it seems after the engine update in 3.25.9.2 this workaround broke: the particle system can be culled at low draw distances. This is understandable from the engine's perspective, as using the particle system's origin for culling is suboptimal. As of March 2026 we're not aware of a workaround to force the particle system to render. **CloudOverride_Prefab** :ref:`Master Bundle Pointer `: Prefab to instantiate and attach to lighting. **CloudOverride_ParticleSystems** *list*: Dictionaries describing particle systems in ``CloudOverride_Prefab`` with the following additional properties: **Path** *string*: Path to a Particle System component relative to ``CloudOverride_Prefab``. This renderer should likely use the Unturned "Particles/Standard Surface (ZClip False)" shader to prevent a harsh transition with low max draw distance. **RateOverTimeScale** *float*: Particle System's emission rate is multiplied by current time of day's cloud slider value (between zero and one) scaled by this value. **MaterialColorPropertyNames** *list*: Particle System's material instance will have these color properties set to the current time of day's cloud color. Defaults to just _Color. **WarmupTime** *float*: When restarting the particle system it is simulated this number of seconds. Alternative to enabling Particle System's ``Prewarm`` option. Defaults to zero. For example: .. code-block:: unturnedasset :linenos: CloudOverride_ParticleSystems [ { Path System1 RateOverTimeScale 1.5 WarmupTime 10 MaterialColorPropertyNames [ _Color _EmissionColor ] } { Path System2 RateOverTimeScale 3 MaterialColorPropertyNames [ _Color _EmissionColor ] } ] Schedulable Weather Properties ------------------------------ **Asset** :ref:`Asset Pointer `: Points to a :ref:`Weather Asset `. **Min_Frequency** *float*: When chosen to be the next scheduled weather event, minimum number of in-game days before it will start. **Max_Frequency** *float*: When chosen to be the next scheduled weather event, maximum number of in-game days before it will start. **Min_Duration** *float*: Minimum number of in-game days before the weather event will end. **Max_Duration** *float*: Maximum number of in-game days before the weather event will end. Skill Rule Properties --------------------- **Id** *string*: Name of skill, for example Sharpshooter. **Default_Level** *int*: Skill level when player spawns. The ``Spawn_With_Max_Skills`` gameplay config option takes priority. **Max_Unlockable_Level** *int*: Maximum skill level attainable through gameplay. Higher levels are hidden in the skills menu. **Base_Cost** *int*: If set, overrides XP cost to purchase first level of the skill. **Per_Level_Cost_Increase** *int*: If set, overrides XP cost increase with each level. Added to ``Base_Cost`` after the first level. **Cost_Multiplier** *float*: Multiplier for total XP upgrade cost. .. code-block:: unturnedasset :linenos: Skills [ { Id Overkill Default_Level 0 Max_Unlockable_Level 0 } { Id Parkour Default_Level 2 Max_Unlockable_Level 2 } { Id Crafting Default_Level 1 Max_Unlockable_Level 3 Cost_Multiplier 5 } ] Skillset Loadout Properties --------------------------- Can contain the following keys: ``None``, ``Fire``, ``Police``, ``Army``, ``Farm``, ``Fish``, ``Camp``, ``Work``, ``Chef``, ``Thief``, ``Medic`` Each key is a list of items with the following properties: **Asset**: :ref:`Asset Pointer `: Item or spawn table to grant an item from. **Amount** *int*: Number of times to grant this item. Defaults to 1. **Origin** :ref:`EItemOrigin `: Determines starting state of the item. Defaults to World. Example: .. code-block:: unturnedasset :linenos: Skillset_Loadouts { Army [ { // Eaglefire at max quality with full ammo Asset 4 Origin Admin } { // Military magazine x2 with random ammo Asset dbfb1d0d11ca438e9dffb95f76e61274 Amount 2 } ] // Other skillsets will spawn with nothing } Terrain Color Properties ------------------------ **Color** :ref:`color `: Actual base color/albedo of terrain material. Players will be kicked from multiplayer servers if their customized skin color is too similar to the value of this property. **HueThreshold** :ref:`float32 `: Values are clamped from 0 to 1. If difference between hues is greater than this threshold, the colors are not too similar. **SaturationThreshold** :ref:`float32 `: Values are clamped from 0 to 1. If difference between saturations is greater than this threshold, the colors are not too similar. **ValueThreshold** :ref:`float32 `: Values are clamped from 0 to 1. If difference between values is greater than this threshold, the colors are not too similar. Music Properties ---------------- **Loop** :ref:`Master Bundle Pointer `: Looping audio clip played until loading finishes. **Outro** :ref:`Master Bundle Pointer `: Audio clip played once loading finishes. ================================================ FILE: assets/material-palette-asset.rst ================================================ .. _doc_assets_material_palette: Material Palette Assets ======================= The ``MaterialPaletteAsset`` type allows an object to have multiple potential materials that it can use. A random material from the material palette is chosen every time the object is spawned in the level editor. In the level editor, material palettes can also be manually assigned to a selected object. Metadata -------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *string*: ``SDG.Unturned.MaterialPaletteAsset`` Material Palette Properties --------------------------- **Materials** *array* of :ref:`Master Bundle Pointer ` *dictionaries*: Each dictionary in the list should point to a material bundled in Unity. .. code-block:: unturnedasset "Asset" { "Materials" [ { "Name" "core.masterbundle" "Path" "Objects/Material_Palettes/House/House_00.mat" } { "Name" "core.masterbundle" "Path" "Objects/Material_Palettes/House/House_01.mat" } ] } ================================================ FILE: assets/mod-hooks.rst ================================================ .. _doc_assets_mod_hooks: Mod Hooks ========= Overview -------- Script Components can be added to Game Objects in Unity and exported in Asset Bundles *IF* they match a script in the base game code. These intentionally exportable scripts are referred to as **Mod Hooks**. They can be imported into a Unity project from the Project.unitypackage, and added to game objects inside the Unturned components menu. Each script makes several Events available which can drive other component properties like visibility or play an animation. Each script documents its purpose and members within its \*.cs file. Originally proposed and coined by VitaxaRusModding in this GitHub issue: `Link `_ Event Listeners --------------- Activation Event Hook ````````````````````` Events when a component or game object are enabled and disabled. Useful for extending toggleable actions in the base game. Binary Random Component ``````````````````````` When triggered will invoke one of two events depending on percentage probability. For example with a probability of 0.05 the OnTrue event will be invoked 5% of the time, and OnFalse will be invoked the remaining 95% of times. Collision Damage `````````````````` Damages players when they overlap a trigger collider. Collision Event Hook ```````````````````` Events for player overlaps with a trigger collider. Primarily useful for server-side objects as collisions are not triggered by other players client-side, but this limitation may be resolved in the future. Destroy Event Hook `````````````````` Event when a component or game object is removed from the scene. Explosion Spawner ````````````````` Allows Unity events to apply damage in a sphere. (doesn't have any visual effects) Intended to replace unsupported/unintentional use of ``Grenade.cs`` and ``Rocket.cs`` scripts. Gun Attachment Event Hook ````````````````````````` Allows gun item game objects (including children) to receive events when sights, tacticals, grips, barrels, and magazines are attached, replaced, and/or detached. .. _doc_assets_mod_hooks:iobs_event_hook: Interactable Object Binary State Event Hook (IOBS) `````````````````````````````````````````````````` (IOBS for short) are any prop placed from the level editor which can have F pressed on them to open, close, turn on/off, etc. This hook can be added to any GameObject within an IOBS to trigger events during state changes, and even control the IOBS from client and server side. Interactable Object Quest Event Hook ```````````````````````````````````` This hook can be added to any GameObject within a Dropper, Note, or Quest Interactable Object. Its event is triggered when the corresponding interactable is successfully used. Note that the event is only triggered on the authority side (i.e., the server or singleplayer) and not on the client. .. _doc_assets_mod_hooks:npc_global_event_hook: NPC Global Event Hook ````````````````````` Event triggered when corresponding :ref:`NPC Event reward ` type is triggered. For example, when any NPC Event with ID "Fireworks" is broadcast all of the components with event ID "Fireworks" will have their corresponding Unity event triggered as well, in this case perhaps to spawn a fireworks effect. Text Chat Event Hook ```````````````````` Event when a text chat message passes certain filters such as channel, within a radius, and containing a secret phrase. Only fired on the server. Timer Event Hook ```````````````` Allows events to set or cancel a timer, and triggers an event when the timer expires. Useable Event Hook ``````````````````` Events for EquipableItem prefab of any item type. These events are fired on server and client. Useable Gun Event Hook `````````````````````` Events for EquipableItem prefab. Supersedes VehicleTurretEventHook. These events are fired on server and client. Vehicle Event Hook `````````````````` Events for driver entering and exiting the vehicle. These events are fired on server and client. Vehicle Gear Shift Event Hook `````````````````````````````` Events for vehicle gearbox entering and exiting a target gear. Vehicle Health Event Hook `````````````````````````` Events for vehicle health passing a comparison against a target number. Vehicle Turret Event Hook ````````````````````````` Events for Turret\_# GameObjects in the vehicle when guns are used. These events are fired on server and client. Weather Event Hook `````````````````` Events for day, night, full moon, and weather. These events are fired on server and client. Custom Weather Event Hook ````````````````````````` Events for a specific custom :ref:`Weather Asset `. Any map can have an unlimited number of weather types and weather listeners. Event Instigators ----------------- Airdrop Spawner ``````````````` Allows Unity events to call in an airdrop. Optionally overrides the cargo and destination. Barricade Spawner ````````````````` Allows Unity events to place barricades. Client Text Chat Messenger `````````````````````````` Allows Unity events to request a text chat message be sent on behalf of the client. For example, to execute a command. The ``UnityEvents.Allow_Client_Messages`` and/or ``UnityEvents.Allow_Client_Commands`` settings must be enabled in the :ref:`doc_servers_server_configuration` before these can be triggered. This ensures hosts are aware of their usage. Singleplayer defaults to enabled. Item Spawner ``````````````` Allows Unity events to spawn dropped items. Server Text Chat Messenger `````````````````````````` Allows Unity events to broadcast messages from the server. Icons and rich text are optional. Can also execute commands that are not available (yet) to NPCs like changing the weather or triggering an airdrop. The ``UnityEvents.Allow_Server_Messages`` and/or ``UnityEvents.Allow_Server_Commands`` settings must be enabled in the :ref:`doc_servers_server_configuration` before these can be triggered. This ensures hosts are aware of their usage. Singleplayer defaults to enabled. Effect Spawner `````````````` Allows Unity events to spawn effect assets. When the ``AuthorityOnly`` field is enabled only the server will spawn effects and replicate them to clients. Mob Alert Spawner ````````````````` Allows Unity events to startle nearby animals and zombies. Optionally uses a nearby player as the origin of the alert. NPC Global Event Messenger `````````````````````````` Allows Unity events to broadcast Event NPC rewards. The ``NPC Global Event Hook`` can then listen for these events. Vehicle Spawner ``````````````` Allows Unity events to spawn a vehicle. Optionally overrides the paint color. Misc ---- Barricade Destroyer ```````````````````` Forcefully removes barricades within a sphere, optionally playing their Explosion effects and/or spawning their Item_Dropped_On_Destroy item(s). Fall Damage Override ```````````````````` Allows any game object to override the fall damage when a character lands on it or one of its descendants. Crafting Tag Provider ````````````````````` Allows the following entities to modify which crafting tags (workstations) are available to nearby players: - Barricades - Structures - Vehicles - Resources - Objects This component is used by vanilla for Heat Source backwards compatibility. Crafting Tag Modifier ````````````````````` Linked from a Crafting Tag Provider. Allows Unity events to modify which crafting tags (workstations) are available to nearby players. As an example: the automatic Heat Source backwards compatibility adds a Crafting Tag Modifier to the Fire game object with an Activation Requirement of Invert and Mode Remove. This removes the Heat Source tag while the Fire is inactive. Music Audio Source ``````````````````` Reassigns a sibling Audio Source's output audio mixer group to the vanilla Music mixer, respecting the player's volume preferences. Repeat `````` Repeats an event a configurable or random number of times. Essentially a for-loop for Unity events. ================================================ FILE: assets/mythical-asset.rst ================================================ .. _doc_assets_mythical: Mythical Effect Assets ====================== **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Mythic``) **ID** *uint16*: Must be a unique identifier. .. note:: At the time of writing (2025-02-04) mythical effects aren't moddable, sorry! This document is primarily for item creators working on curated updates, as well as preparation for eventual open sourcing. When testing, we recommend attaching your mythicals to some items' Effect transform in the editor and resetting the local transform. This helps visualize how they will appear in-game. Unity Prefabs ------------- **System_Area**: Instantiated multiple times to cover a larger area. Mythical shirts and pants attach them to character bones, and mythical vehicle skins attach them to several points on the surface. As such, this shouldn't rely on any specific orientation. Layer should be set to Enemy. **System_Hook**: Attached to a cosmetic item's "Effect" prefab. Layer should be set to Enemy. .. figure:: /img/EffectTransform.png Example "Effect" transform positioning and orientation. For silly legacy reasons the orientation is rather unfortunate: +Z is the mythical's up direction and +Y is the mythical's forward direction. **System_Third**: Attached to third-person weapon skin. Unlike for cosmetics, +Z is forward and +Y is up. It may be helpful to increase particle size to make them more visible over the shoulder. Emission typically uses a box of size 25x25x50 cm. Layer should be set to Item. **System_First**: Attached to first-person weapon skin. Particles should be smaller than usual, and try to avoid the up direction to reduce blocking the player's aim. First-person particles are typically half the size, but use the same emission shape size as third-person. Layer should be set to Viewmodel. Localization ------------ **Particle_Tag_Name** *string*: When a mythical item is crafted with this effect, this is the display name shown in the inventory. ================================================ FILE: assets/object-asset.rst ================================================ .. _doc_assets_object: Object Assets ============= **GUID** *32-digit hexadecimal*: Refer to :ref:`doc_data_guid` documentation. **Type** :ref:`EObjectType `: The object's type is used for sorting, pathfinding, collision, and culling. Small objects are used for clutter and decoration, medium objects fill out the layout, and large objects make up the level. When using the ``NPC`` enumerator, refer to the documentation for :ref:`doc_object_asset_npc` as well. **ID** *uint16*: Must be a unique identifier. Object Properties ----------------- **Add_Kill_Triggers** *bool*: If true, this adds a kill volume inside the object that will kill players who clip inside it. This is helpful for preventing out-of-bounds exploits, such as players trying to build bases inside boulder objects. **Add_Night_Light_Script** *flag*: Adds a script to the object that looks for a transform named "Light". During the night, the light will be turned on. During the day, the light will be turned off. **Allow_Structures** *flag*: Structures can be built on top of this object. For example, a fake grass object may want to use this property. **Causes_Fall_Damage** *bool*: Whether or not players should take fall damage when landing on this object. Defaults to true. **Chart** *enum* (:ref:`doc_data_eobjectchart`): When an object obstructs the terrain, it can appear on a map's chart view. The pixel sampled for the object's color on the chart view can be set or overridden with this property. By default, ``Type Large`` objects use the same pixel as the ``Large`` enumerator, and ``Type Medium`` objects use the same pixel as the ``Medium`` enumerator. Defaults to ``Ignore`` when using ``Type NPC`` or ``Type Decal``. Otherwise, defaults to ``None``. **Christmas_Redirect** :ref:`doc_data_guid`: GUID of the object that should appear during the Festive holiday. **Collision_Important** *flag*: Prevent collision from being disabled. When using ``Type Large``, this flag is automatically included. **Exclude_From_Level_Batching** *bool*: Exclude this object from :ref:`level batching `. This property may be helpful when using elaborate setups with Unity Event components. Defaults to true when using ``Type Decal`` or ``Type NPC``. **Foliage** :ref:`GUID `: GUID of a :ref:`foliage asset `. This property is useful for objects such as fake grass, which may want foliage to bake on top of the object similar to terrain materials. **Fuel** *flag*: Fuel can be siphoned from this object. Deprecated in favor of ``Interactability Fuel``. **Halloween_Redirect** :ref:`doc_data_guid`: GUID of the object that should appear during the Halloween holiday. **Has_Clip_Prefab** *bool*: Whether or not the object has a Clip.prefab. If the object should use the same prefab on the server as on the client, set to false. For example, most official content uses ``Has_Clip_Prefab false``. Defaults to true. **Holiday_Restriction** *enum* (:ref:`doc_data_enpcholiday`): If a valid value is specified, then this object will only be visible during the corresponding holiday. The specified holiday will be appended to the object's user-friendly name. Defaults to ``None``. **Is_Gore** *bool*: Whether or not this object should be visible if the player has disabled "Show Blood Splatters". **Is_Clutter** *bool*: Defaults to false. If true, object is not instantiated when player has the "Load Clutter" graphics option disabled. .. warning:: Objects the player can collide with should never be clutter. Otherwise, the player will "rubberband" on these objects in multiplayer. **Landmark_Quality** *enum* (``Off``, ``Low``, ``Medium``, ``High``, ``Ultra``): The value that the "Landmarks" graphical setting must be set to in order to see a low detail model of this object from far away distances. Defaults to ``Low``. **Load_Nav_On_Server** *bool*: If true, Nav game object will be instantiated in singleplayer and on dedicated server. Useful for objects which need to affect navmesh baking without colliding with zombies during gameplay. Defaults to true for "medium" and "large" objects. **Load_Nav_In_Editor** *bool*: If true, Nav game object will be instantiated in the level editor. Useful for objects which need collision with zombies during gameplay without affecting navmesh baking. Defaults to true for "medium" and "large" objects. **Material_Palette** :ref:`doc_data_guid`: GUID of the :ref:`Material Palette Asset ` that should be used by the object. **Refill** *flag*: Water can be siphoned from this object. Deprecated in favor of ``Interactability Water``. **Snowshoe** *flag*: This object should not leave a footprint when baking materials. **Soft** *flag*: Vehicles should not take damage when colliding with this object. **Use_Water_Height_Transparent_Sort** *flag*: Useful for transparent objects, such as glass. **Exclude_From_Satellite_Capture** *bool*: If true, object will be hidden when rendering GPS/satellite view. Defaults to true if ``Holiday_Restriction`` is other than ``None``. Decals `````` **Decal_Alpha** *flag*: This flag should be set if the decal has a transparent texture. Requires ``Type Decal``. **Decal_X** *float*: Override the scale of the decal, on the 𝘟-axis. Requires ``Type Decal``. **Decal_Y** *float*: Override the scale of the decal, on the 𝘠-axis. Requires ``Type Decal``. **Decal_LOD_Bias** *float*: Multiplier for the LOD's switching distance. Defaults to 1. Requires ``Type Decal``. Interior Culling ```````````````` **Exclude_From_Culling_Volumes** *bool*: If set to true, this object will not be managed by culling volumes. For example, the aerospace facility on the Germany map is excluded from culling volumes, so that manually-placed culling volumes can hide large objects like shipping containers without accidentally hiding the giant aerospace facility itself. **LOD** *enum* (``None``, ``Mesh``, ``Area``): How interior culling should be determined. Using the ``Mesh`` enumerator will use the mesh bounds to determine what is inside the object. For concave objects, you can use the ``Area`` enumerator instead and add multiple Occlusion Area components for the interior volumes. **LOD_Bias** *float*: Multiplier on the threshold distance for interior culling. Requires that ``LOD`` has been set. **LOD_Center_X** float: Offset for the culling volume's local position, on the 𝘟-axis. Requires that ``LOD`` has been set. **LOD_Center_Y** float: Offset for the culling volume's local position, on the 𝘠-axis. Requires that ``LOD`` has been set. **LOD_Center_Z** float: Offset for the culling volume's local position, on the 𝘡-axis. Requires that ``LOD`` has been set. **LOD_Size_X** float: Offset for the culling volume's size, on the 𝘟-axis. Requires that ``LOD`` has been set. **LOD_Size_Y** float: Offset for the culling volume's size, on the 𝘠-axis. Requires that ``LOD`` has been set. **LOD_Size_Z** float: Offset for the culling volume's size, on the 𝘡-axis. Requires that ``LOD`` has been set. Interactables ````````````` **Interactability** *enum* (``None``, ``Binary_State``, ``Dropper``, ``Note``, ``Water``, ``Fuel``, ``Rubble``, ``NPC``, ``Quest``, ``Dialogue``): All ``Interactability_`` properties will require that this property has been set. The enumerator selected for this property will affect which properties can be used, how these properties will function when used, and how this object will behave in-game. Defaults to the ``NPC`` enumerator when using ``Type NPC``, otherwise this property will default to ``None``. - ``Binary_State`` objects will change between their two states when interacted with – such as an open or closed door. - ``Dropper`` objects can spawn items when interacted with. - ``Note`` objects can display lines of text when interacted with. - ``Water`` objects can be siphoned for water, and ``Fuel`` objects can be siphoned for fuel. - ``Rubble`` objects are destructible. It is preferable to use ``Rubble Destroy`` instead of ``Interactability Rubble``. - ``NPC`` objects can provide access to dialogue, quests, and vendors. - ``Quest`` objects can be interacted with, but unlike other options they have no additional functionality. - ``Dialogue`` objects open the dialogue screen - similar to NPCs - with a non-NPC appearance and custom interact text. .. note:: Although ``Interactability`` properties can be used to create a destructible object, it is preferable to use ``Rubble`` properties as they are more specific. This allows for creating destructible objects that are also interactable. **Interactability_Animation_Component_Path** *string*: (``Binary_State``-only) Transform path relative to object root with Animation component. Defaults to "Root". **Interactability_Blade_ID** *byte*: When using ``Interactability Rubble``, weapons are unable to damage this object unless they have a matching ``BladeID_#`` value. Defaults to 0. **Interactability_Delay** *float*: In seconds, the cooldown before the object can be interacted with again. **Interactability_Dialogue** :ref:`doc_data_guid`: Dialogue asset to open for ``Interactability Dialogue`` mode. By default the object's name is used as the character name in dialog, but this can be overridden with the ``Dialogue_Name`` option in the localization file. **Interactability_Drops** *byte*: Total number of items dropped from an object using ``Interactability Dropper``. This property is used in conjunction with ``Interactability_Drop_#``. Defaults to 0. It is preferable to use the ``Interactability_Reward_ID`` property instead. **Interactability_Drop_#** *uint16*: ID of an item that should be dropped. This property is used in conjunction with ``Interactability_Drops``. **Interactability_Editor** *enum* (``None``, ``Toggle``): Determines how this interactable object should appear in the level editor. If this is set to ``Toggle``, then the object's alternative state will be shown. Defaults to ``None``. **Interactability_Effect** :ref:`doc_data_guid` or *uint16*: GUID or legacy ID of an :ref:`EffectAsset ` to play when interacted with. When using ``Interactability Rubble``, this effect is played when a section of the object is destroyed. **Interactability_Emissive_Material_Mode** *enum* (``Auto`` or ``None``): (``Binary_State``-only). Defaults to ``Auto``, creating a material instance for child renderer of ``Toggle`` game object. The downside of ``Auto`` is exclusion from the level batching texture atlas. When set to ``None``, no material instance is created. **Interactability_Finale** :ref:`doc_data_guid` or *uint16*: GUID or legacy ID of an :ref:`EffectAsset ` to play when all sections of the object using ``Interactability Rubble`` are destroyed. If this property is used, then all of the dead object's sections will also be hidden when fully destroyed. **Interactability_Health** *uint16*: Total amount of health each section of the object has, when using ``Interactability Rubble``. Defaults to 0. **Interactability_Hint** *enum* (``Door``, ``Switch``, ``Fire``, ``Generator``, ``Use``, ``Custom``): Localization key to use for the interact prompt. Setting this to ``Custom`` allows for displaying custom text instead, when used in conjunction with ``Interact``. **Interactability_Invulnerable** *flag*: This resource cannot be damaged by lower-power :ref:`doc_item_asset_weapon` that do not have the ``Invulnerable`` flag, when using ``Interactability Rubble``. **Interactability_Nav** *enum* (``None``, ``On``, ``Off``): When using ``Binary_State``, controls how on/off state affects ``Nav`` game object. Defaults to ``None`` which doesn't affect Nav. ``On`` activates Nav when object is in the on state and deactivates in the off state. (``Off`` does the opposite.) .. note:: When ``Interactability_Nav`` is combined with ``Rubble_Nav_Mode``, the Nav game object is only active if **both** activate it. (i.e., AND) **Interactability_Power** *enum* (``None``, ``Toggle``, ``Stay``): Whether or not this object must be powered to be usable. When set to ``None``, this object cannot be powered. When set to ``Toggle``, the object must be powered to be interacted with. When set to ``Stay``, the object must be powered to remain on. For example, a door might use ``Toggle`` if it should remain open after it loses power, while a streetlight might use ``Stay`` so that the light turns off when it loses power. Defaults to ``None``. **Interactability_Proof_Explosion** *flag*: Immune to area-of-effect explosive damage, when using ``Interactability Rubble``. **Interactability_Remote** *flag*: Disables the ability for players to interact with this via a button prompt. **Interactability_Reset** *float*: Delay before an interacted object resets, or a destroyed object respawns, in seconds. **Interactability_Resource** *uint16*: When using ``Interactability Fuel`` or ``Interactability Water``, this value is how many units of fuel or water is stored in the object. Defaults to 0. **Interactability_Reward_ID** *uint16*: ID of an item :ref:`spawn table ` to use for rewards, when using ``Interactability Rubble``. Defaults to 0. **Interactability_RewardItem_Origin** :ref:`doc_data_eitemorigin`: When using ``Interactability Dropper``, overrides the dropped item's state. For example, setting the origin to ``Admin`` will cause items to spawn at full quality. Defaults to ``Nature``. **Interactability_Rewards_Min** *byte*: Minimum amount of item drops to reward, when using ``Interactability Rubble``. Defaults to 1. **Interactability_Rewards_Max** *byte*: Maximum amount of item drops to reward, when using ``Interactability Rubble``. Defaults to 1. **Interactability_Reward_Probability** *float*: Probability of receiving a reward, as a decimal-to-percent chance, when using ``Interactability Rubble``. Defaults to 1. **Interactability_Reward_XP** *uint32*: Amount of experience to reward when the object using ``Interactability Rubble`` is destroyed. **Interactability_Text_Lines** *uint16*: Total number of lines to display when an object using ``Interactability Note`` is interacted with. This property is used in conjunction with ``Interactability_Text_Line_#``. Defaults to 0. Rubble `````` **Rubble** *enum* (``None``, ``Destroy``): The destruction mode that should be used, although the only functional option for this is ``Destroy``. All ``Rubble_`` properties require that this property has been set. **Rubble_All_Sections_Destroyed_Alert_Radius** *float*: If set, alert nearby enemies when all sections are destroyed. **Rubble_Blade_ID** *byte*: Weapons are unable to damage this object unless they have a matching ``BladeID_#`` value. Defaults to 0. **Rubble_Can_Zombies_Damage** *bool*: If true, zombies can attack this object if it's blocking them. Defaults to false. **Rubble_Editor** *enum* (``Alive``, ``Dead``): Determines how this destructible object should appear in the level editor. If this is set to ``Dead``, the fully destroyed state of the object will be shown. Defaults to ``Alive``. **Rubble_Effect** :ref:`doc_data_guid` or *uint16*: GUID or legacy ID of an :ref:`EffectAsset ` to play when a section of the destructible object is destroyed. **Rubble_Finale** :ref:`doc_data_guid` or *uint16*: GUID or legacy ID of an :ref:`EffectAsset ` to play when all sections of the destructible object are destroyed. If this property is used, then all of the dead object's sections will also be hidden when fully destroyed. **Rubble_Health** *uint16*: Total amount of health each section of the object has. Defaults to 0. **Rubble_Invulnerable** *flag*: This resource cannot be damaged by lower-power :ref:`doc_item_asset_weapon` that do not have the ``Invulnerable`` flag. **Rubble_Nav_Mode** *enum* (``Unaffected``, ``DeactivateIfAllDead``): Defaults to ``Unaffected``. ``DeactivateIfAllDead`` deactivates the Nav game object when all rubble sections are destroyed, but keeps it active otherwise. .. note:: When ``Rubble_Nav_Mode`` is combined with ``Interactability_Nav``, the Nav game object is only active if **both** activate it. (i.e., AND) **Rubble_Proof_Explosion** *flag*: Immune to area-of-effect explosive damage. **Rubble_Reset** *float*: Delay before a destroyed object respawns, in seconds. **Rubble_Respawn_All_Sections_Simultaneously** *bool*: If true, all sections respawn at the same time. Defaults to false. **Rubble_Reward_ID** *uint16*: ID of an item :ref:`spawn table ` to use for rewards. Defaults to 0. **Rubble_Rewards_Min** *byte*: Minimum amount of item drops to reward. Defaults to 1. **Rubble_Rewards_Max** *byte*: Maximum amount of item drops to reward. Defaults to 1. **Rubble_Reward_Probability** *float*: Probability of receiving a reward, as a decimal-to-percent chance. Defaults to 1. **Rubble_Reward_XP** *uint32*: Amount of experience to reward when the destructible object is destroyed. **Rubble_Section_Destroyed_Alert_Radius** *float*: If set, alert nearby enemies when an individual section is destroyed. Not used when the final section is destroyed—in that case, **Rubble_All_Sections_Destroyed_Alert_Radius** applies instead. **Rubble_Zombie_Damage_Multiplier** *float*: Multiplier for damage from zombies if RubbleCanZombiesDamage is true. Conditions and Rewards `````````````````````` :ref:`Conditions ` can be used to control the visibility of an object. For example, if an object should only be visible after a certain quest has been completed. These properties do not have a unique prefix, and instead use the standard ``Conditions`` and ``Condition_#`` property names. Conditions and :ref:`rewards ` can also be tied to the interactability of an object. An object could become interactable during a quest, and then trigger rewards (such as completing the quest) once it has been interacted with. These properties are prefixed with ``Interactability_``. For example, ``Interactability_Conditions`` and ``Interactability_Reward_#``. Localization ------------ **Name** *string*: Object name in user interfaces. **Interact** *string*: When an interactable object is using ``Interactability_Hint Custom``, this property is used to set the text that should be displayed as the interact prompt for the object. **Interactability_Text_Line_#** :ref:`doc_data_richtext`: A line of text that should be displayed when an object using ``Interactability Note`` is interacted with. This property is used in conjunction with ``Interactability_Text_Lines``. **Dialogue_Name** *string*: Overrides character name in dialogue. Defaults to the object name. ================================================ FILE: assets/outfit-asset.rst ================================================ .. _doc_assets_outfit: Outfit Assets ============= The OutfitAsset class allows for defining a selection of clothing items that should be worn together when generating preview images for outfits. Outfit preview images can be generated with the \[F1] menu available from the Workshop section of the main menu. Metadata -------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *string*: ``SDG.Unturned.OutfitAsset`` Outfit Properties ----------------- **Items** *array* of :ref:`Asset Pointers `: Asset pointers to clothing item(s). These clothing items will be worn together in any preview images generated of this outfit. For example: .. code-block:: unturnedasset "Asset" { "Items" [ // Top "9fd6032f9a24404eaf28961fc7f2d289" // Bottom "d4ec52a157f746edbc3a4df8ae79ddef" // Mask "1adc30f0dbf246eba1c0c6a183206aad" // Hat "daf02a225ebc4b76ae51ca485706e470" ] } ================================================ FILE: assets/physics-material-asset.rst ================================================ .. _doc_assets_physics_material: Physics Material Assets ======================= Work-in-progress feature to allow custom physics effects rather than hardcoding them. The ``PhysicsMaterialAsset`` type associates gameplay properties and effects with custom Unity "physic" materials. For example if none of the built-in physics materials has appropriate effects for the surface of Mars, a custom Unity physics material named "MarsDirt" could be created. Then a physics material asset with ``UnityName`` set to "MarsDirt" and ``Fallback`` of 33650ff924b34f8d9c5a0fd97418cd3e (built-in gravel) could add custom effects for the Martian surfaces. The ``PhysicsMaterialExtensionAsset`` type can be used to insert custom properties into built-in physics materials. For example if a custom laser gun should leave burn marks on the hit surface rather than bullet holes, an extension asset can set the ``Base`` property to a built-in physics material to add custom effects. Properties ---------- **Type** *string*: ``SDG.Unturned.PhysicsMaterialAsset`` or ``SDG.Unturned.PhysicsMaterialExtensionAsset`` **UnityName** *string* or ``UnityNames`` *string array*: Names of Unity "physic" materials to associate with this asset. Not set by extension assets. Multiple names can be specified as an array because the old built-in physics materials had several variants for special cases that should now be handled by these assets. **Fallback** :ref:`Asset Pointer `: Points to a different physics material asset. Fallbacks are used when a property is not set. For example the snow physics material does not have a bullet casing bounce audio clip, so the gravel fallback is used instead. **Base** :ref:`Asset Pointer `: Points to a physics material asset to extend. Properties from the extension asset will be appended to the base asset. **AudioDefs** *dictionary*: pairs of key/name and :ref:`Master Bundle Pointer ` to OneShotAudioDefinition. For example the ``ParticleSystemCollisionAudio`` component ``MaterialPropertyName`` is referring to these keys. Official properties include: - BulletCasingBounce: used by vanilla non-shotgun particle collision audio. - BulletImpact: fired bullet hitting surface. - BipedLand: player landing on a surface after falling. Could be used for other two-legged characters in the future. - FootstepWalk: individual non-sprinting footstep. - FootstepRun: individual sprinting footstep. - LegacyImpact: will probably be phased-out. Still used by vehicle bumper collision and as a fallback for melee impact. - MeleeImpact: melee attack hitting surface. - ShotgunShellBounce: used by vanilla shotgun particle collision audio. - ZombieBipedLand: zombie equivalent of BipedLand. If unassigned, BipedLand is used with 85% pitch scaling. - ZombieFootstepRun: zombie equivalent of FootstepRun. If unassigned, FootstepRun is used with 85% pitch scaling. - ZombieFootstepWalk: zombie equivalent of FootstepWalk. If unassigned, FootstepWalk is used with 85% pitch scaling. - MegaZombieFootstep: mega zombie footstep sound. If unassigned, FootstepWalk is used with 72% pitch scaling and +50% volume. - MegaZombieLand: mega zombie landing sound. If unassigned, BipedLand is used with 72% pitch scaling and +50% volume. **TireMotionEffect** :ref:`Asset Pointer ` to :ref:`Effect Asset `: Effect to spawn while driving on this material. Its transform is set to the ground hit position with the Z axis aligned to the wheel's up vector and rotated according to forward/reverse speed. The vanilla effects use the rate over distance emission mode. **IsArable** *bool*: If true, crops can be planted on this material. **HasOil** *bool*: If true, oil drills can be placed on this material. Note at the time of writing (2022-02-10) oil drills can only be placed on terrain materials. **Character_Friction_Mode** *enum* (``ImmediatelyResponsive``, ``Custom``): If custom the acceleration, deceleration, and max speed properties are used. Replacement for the hardcoded ice and slippery metal plate. **Character_Acceleration_Multiplier** *float*: Default acceleration is equal to the target move speed. **Character_Deceleration_Multiplier** *float*: Default deceleration is 2m/s². ``Character_Max_Speed_Multiplier`` *float*: Allows speed to reach up to this multiplied by the target move speed. ================================================ FILE: assets/redirector-asset.rst ================================================ .. _doc_asset_redirector: Redirector Assets ================= **Redirector Assets** are a special asset type only used when resolving asset references (GUIDs and legacy IDs). When an asset reference points to a redirector, the asset system instead returns the asset pointed to by the redirector. .. note:: Most features do not save the resolved asset, instead they save the original asset reference. This means, for example, that redirecting some objects and re-saving a level will save the original object references, not the redirected objects. Game Data File -------------- Note that ``TargetAsset`` is required for this asset to function. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`AssetCategory ` - :ref:`enum ` - ``None`` * - :ref:`TargetAsset ` - :ref:`GUID ` - Property Descriptions ````````````````````` .. _doc_asset_redirector:assetcategory: AssetCategory :ref:`EAssetType ` ``None`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If set, an asset's legacy ID can be redirected as well. For example: a redirector with ``AssetCategory Item`` that is pointing to an asset with the legacy ID of ``4``, would be found when using ``/give 4``. ---- .. _doc_asset_redirector:targetasset: TargetAsset :ref:`GUID ` ::::::::::::::::::::::::::::::::::::::: GUID of actual asset to use when an asset reference points to the redirector asset. ================================================ FILE: assets/resource-asset.rst ================================================ .. _doc_assets_resource: Resource Assets =============== **GUID** *32-digit hexadecimal*: Refer to :ref:`doc_data_guid` documentation. **Type** *enum* (``Resource``) **ID** *uint16*: Must be a unique identifier. Resource Properties ------------------- **Auto_Skybox** *flag*: Generate and assign a material and texture to the resource's Skybox prefab. The mesh should have custom normals to match the lighting. For example, vanilla pine trees have upward normals, whereas spherical trees have outward normals. **BladeID** *byte*: Weapons are unable to damage this resource unless they have a matching ``BladeID_#`` value. Defaults to 0. **Bypass_ID_Limit** *flag*: Allows for using an ``ID`` value within the range reserved for official content. **Chart** *enum* (:ref:`doc_data_eobjectchart`): When a resource obstructs the terrain, it can appear on a map's chart view. The pixel sampled for the resource's color on the chart view can be set or overridden with this property. Defaults to ``None``, and will sample (14, 0) from the Layer_Strip. **Christmas_Redirect** :ref:`doc_data_guid`: GUID of the resource that should appear during the Festive holiday. **Debris_Vertical_Offset** *float*: Distance along tree's local up axis to offset debris spawn position. Defaults to 1.0. **Exclude_From_Level_Batching** *bool*: Exclude this resource from :ref:`level batching `. This property may be helpful when using elaborate setups with Unity Event components. Defaults to true when the ``SpeedTree`` flag is set. **Explosion** :ref:`GUID ` or *uint16*: GUID or legacy ID of :ref:`EffectAsset ` to play when destroyed. **Forage** *flag*: Instead of being destroyable, this resource can be foraged from by interacting with it. **Forage_Reward_Experience** *uint32*: Amount of experience to reward when the resource is foraged from. Defaults to 1. **Halloween_Redirect** :ref:`doc_data_guid`: GUID of the resource that should appear during the Halloween holiday. **Health** *uint16*: Total amount of health the resource has. Defaults to 0. **Holiday_Restriction** *enum* (:ref:`doc_data_enpcholiday`): If a valid value is specified, then this resource will only be visible during the corresponding holiday. The specified holiday will be appended to the resource's user-friendly name. Defaults to ``None``. **Ignore_Collision_Between_Stump_And_Debris** *bool*: If true, prevent collisions between falling tree and the stump. (i.e., debris can fall through stump) Defaults to true. **Log** *uint16*: ID of an item that should be dropped when the resource is destroyed. Before multipliers, this item is dropped in bunches of 3 to 7. Defaults to 0. Deprecated in favor of ``Reward_ID``. **No_Debris** *flag*: This resource does not have debris that should appear when it has been destroyed. **RandomAngleDeviation_Max** *float*: Maximum angle in degrees away from the up direction. Defaults to 5. **RandomAngleDeviation_Min** *float*: Minimum angle in degrees away from the up direction. For example, can be set to 0 to allow the tree to be perfectly upright, or a higher value to prevent the tree from ever being upright. Defaults to 5. **RandomUniformScale_Max** *float*: Maximum scale. The same randomized value is used for all axes (uniform). Defaults to 1.1 for backwards compatibility. **RandomUniformScale_Min** *float*: Minimum scale. The same randomized value is used for all axes (uniform). Defaults to 1.1 for backwards compatibility. **Reset** *float*: Delay before respawning, in seconds. **Reward_ID** *uint16*: ID of an item :ref:`spawn table ` to use for rewards. Defaults to 0. **Reward_Min** *byte*: Minimum amount of item drops to reward. Defaults to 6. **Reward_Max** *byte*: Maximum amount of item drops to reward. Defaults to 9. **Reward_XP** *uint32*: Amount of experience to reward when the resource is destroyed. **Scale** *float*: The tree's in-game scale is a random number between 1.1 and the result of ``1.1 + (Scale * 2)``. .. deprecated:: 3.24.7.0 Scale is replaced by the ``RandomUniformScale_Min`` and ``RandomUniformScale_Max`` properties. **SpeedTree** *flag*: This resource should be considered a SpeedTree when using higher graphical settings. **SpeedTree_Default_LOD_Weights** *flag*: Use the default LOD weights intended for a SpeedTree. **Stick** *uint16*: ID of an item that should be dropped when the resource is destroyed. Before multipliers, this item is dropped in bunches of 2 to 5. Defaults to 0. Deprecated in favor of ``Reward_ID``. **Vertical_Offset** *float*: A vertical offset above or below wherever this resource is placed, in meters. Defaults to -0.75. **Vulnerable_To_All_Melee_Weapons** *bool*: When true, this resource can be damaged by melee weapons that do not have a corresponding ``BladeID_#`` value. Defaults to false. **Vulnerable_To_Fists** *bool*: When true, this resource can be damaged by a player's fists. Defaults to false. Localization ------------ **Name** *string*: Resource name in user interfaces. **Interact** *string*: Override the text shown for interactable resources using the ``Forage`` flag. ================================================ FILE: assets/road-asset.rst ================================================ .. _doc_assets_road: Road Assets =========== This asset allows roads to be shared between levels, and exposes some previously-unavailable properties for configuration. Properties ---------- .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Chart ` - :ref:`doc_data_eobjectchart` - ``None`` * - :ref:`Depth ` - :ref:`float32 ` - ``0.0`` * - :ref:`OffsetAlongNormal ` - :ref:`float32 ` - ``0.0`` * - :ref:`PhysicsMaterial ` - :ref:`string ` - See description * - :ref:`RepeatDistanceScale ` - :ref:`float32 ` - ``1.0`` * - :ref:`TexturePath ` - :ref:`string ` - See description * - :ref:`Width ` - :ref:`float32 ` - ``0.0`` * - :ref:`VanillaPhysicsMaterial ` - :ref:`enum ` - See description ---- .. _doc_assets_road:chart: Chart :ref:`doc_data_eobjectchart` ``None`` ::::::::::::::::::::::::::::::::::::::::::: If not ``None``, overrides how road appears in chart generation. If ``None`` (default) legacy classification is used: - Concrete roads wider than 16 meters are ``Highway``. - Other concrete roads are ``Road``. - Non-concrete roads are ``Path``. ---- .. _doc_assets_road:depth: Depth :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Total size along the up axis. .. note:: If converting a legacy road configuration, please note that Depth shown in the legacy editor is actually *half* the total depth. ---- .. _doc_assets_road:offsetalongnormal: OffsetAlongNormal :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Distance along the terrain surface normal to move each road vertex. ---- .. _doc_assets_road:physicsmaterial: PhysicsMaterial :ref:`doc_data_masterbundleptr` to ``PhysicMaterial`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Unity ``PhysicMaterial`` to apply to road collider. Not used if :ref:`VanillaPhysicsMaterial ` is assigned. ---- .. _doc_assets_road:repeatdistancescale: RepeatDistanceScale :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: By default, Texture is uniformly scaled along the road according to its aspect ratio and the road's width. For example, if :ref:`Width ` is 8 meters and Texture is 256x128 pixels, the texture will repeat every 4 meters. This property multiplies the distance along the road before the texture repeats. .. note:: If converting a legacy road configuration, the repeat distance was the texture's height in pixels divided by the Height value. For example: a 64x64 pixel texture with Height of 2 would repeat every 32 meters. To calculate an equivalent RepeatDistanceScale, divide the legacy repeat distance by the road asset's Width. ---- .. _doc_assets_road:texturepath: TexturePath :ref:`doc_data_masterbundleptr` to ``Texture2D`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If not specified, the game looks for a texture named ``Texture`` in the accompanying asset bundle. ---- .. _doc_assets_road:width: Width :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Total horizontal size before the road begins tapering off into the terrain. .. note:: If converting a legacy road configuration, please note that Width shown in the legacy editor is actually *half* the total width. ---- .. _doc_assets_road:vanillaphysicsmaterial: VanillaPhysicsMaterial :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Optional name of a built-in Unity ``PhysicMaterial`` to apply to road collider. For example, "Concrete_Static" or "Gravel_Static" for the legacy road physics materials. ================================================ FILE: assets/server-browser-curation-asset.rst ================================================ .. _doc_asset_server_browser_curation: Server Browser Curation Assets ============================== Most of the information for this asset type is covered in :ref:`Server Browser Curation `. **Type**: ``ServerCuration`` **Icon**: Unlike curation lists hosted on the web, the asset can include a 32x32 Icon texture in an asset bundle. **Name**: If a localization file is present, the display name is loaded from that instead of the asset file. .. note:: The asset is not enabled by default when subscribed to. It needs to be enabled from the Curation menu in the Server Browser. ================================================ FILE: assets/spawn-asset.rst ================================================ .. _doc_assets_spawn: Spawn Assets ============ The spawn asset type represents the weighted chances of an individual item, vehicle, or animal spawning at an any given spawn point. Create custom spawn tables that can be used on custom, curated, and official maps. **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Spawn``) **ID** *uint16*: Must be a unique identifier. IDs 1‒1000 are reserved for official content. Tables ------ Tables are the assets spawned from the spawner, referenced by ID. These could be additional spawn tables; or individual assets like items, vehicles, and animals. **Tables**: list of dictionaries. Each dictionary entry can contain these properties: **Guid** :ref:`GUID `: GUID of an asset to spawn or a spawn table to recursively spawn a child from. Used if ``LegacySpawnId`` and ``LegacyAssetId`` are both unset or zero. **LegacySpawnId** *uint16*: ID of a spawn table to recursively spawn a child from. Use of ``Guid`` is encouraged instead to prevent ID conflicts between mods. **LegacyAssetId** *uint16*: ID of asset to spawn. Use of ``Guid`` is encouraged instead to prevent ID conflicts between mods. **Weight** *int32*: Weight of this entry in the table. For example, this configuration has a 90% chance of spawning a Military Magazine and a 10% chance of spawning an Eaglefire: .. code-block:: text Tables [ { // Military Magazine Guid dbfb1d0d11ca438e9dffb95f76e61274 Weight 180 } { // Eaglefire Guid b03d581a5c1a490f995f8deba57b0f17 Weight 20 } ] .. note:: This older format is used by most spawn assets. The newer format is recommended because it is more user-friendly, but the older format will continue to be supported. **Tables** *int32*: Total number of children. **Table_#_Spawn_ID** *uint16*: ID of a spawn table to recursively spawn a child from. **Table_#_Asset_ID** *uint16*: ID of asset to spawn. **Table_#_Weight** *int32*: Weight of this child in the table. **Table_#_GUID** :ref:`GUID `: GUID of an asset to spawn or a spawn table to recursively spawn a child from. Used if ``Spawn_ID`` and ``Asset_ID`` are both unset or zero. Roots ----- Roots are the spawners that your spawn table will attach itself to. This is useful when adding new spawn tables to preexisting spawn tables, such as those used by official maps. Tables are the things that will get spawned by your spawner. A spawner at the bottom of the chain will be entirely assetIDs, whereas one near the top will likely be entirely spawnIDs. **Roots**: list of dictionaries. Each dictionary entry can contain these properties: **Guid** :ref:`GUID `: GUID of parent spawn table. Used if ``LegacySpawnId`` is unset or zero. **LegacySpawnId** *uint16*: ID of parent spawn table. Use of ``Guid`` is encouraged instead to prevent ID conflicts between mods. **IsOverride** *bool*: If true, zeroes the weight of default spawns in the parent spawn table. Useful for mods intended to replace official content, such as with total conversions. **Weight** *int32*: Weight of this entry in the parent spawn table. .. note:: This older format is used by most spawn assets. The newer format is recommended because it is more user-friendly, but the older format will continue to be supported. **Roots** *int32*: Total number of parents. **Root_#_Spawn_ID** *uint16*: ID of parent spawn table. **Root_#_Override** *flag*: Zeroes the weight of default spawns in the parent spawn table. Useful for mods intended to replace official content, such as with total conversions. **Root_#_Weight** *int32*: Weight of this entry in the parent spawn table. **Root_#_GUID** :ref:`GUID `: GUID of parent spawn table. Used if ``Spawn_ID`` is unset or zero. Exporting Legacy Spawn Tables ----------------------------- Legacy spawn tables can be created within the level editor. For the most, using the legacy spawn system is probably fine for most modded maps. But if you would like to take advantage of automatically keeping up-to-date with new official content—along with better supporting modded content on your map—then you should create spawn assets instead. You might have already created some legacy spawn tables within the level editor. Fortunately, it is fairly straightforward to export those tables as spawn assets! Open your map in the level editor. When you are ready to export, open the pause menu. Next to the button called "Legacy Spawns", enter a number above ``1000`` that should be used as the starting ID for your converted tables. Clicking the "Legacy Spawns" button will now generate spawn assets based on your legacy spawn tables. This process will usually only take a couple seconds. As part of this process, all of the legacy spawn tables on your map will be automatically updated to point to your newly-created spawn assets instead. You should save the game before exiting. These files will appear within a subfolder named "Exported_Legacy_Spawn_Tables", located within your map's folder. Root tables are prefixed with the map's name, while the converted tiers have been prefixed with the table's name. To start using your converted tables, create a folder named "Bundles" within your map folder, and move the contents of the "Exported_Legacy_Spawn_Tables" folder into it. .. tip:: You can use the "Proxy Tables" button to generate empty spawn asset files instead! This is a quick way to get started with creating spawn assets on a newly-created map, where you do not have any legacy spawn tables that need to be converted. Along with converting the map's legacy spawn tables, the game will generate a spreadsheet named "IDs.csv". This spreadsheet can be used to more easily keep track of the IDs of each of your spawn assets. ================================================ FILE: assets/stereo-song-asset.rst ================================================ .. _doc_assets_stereo_song: Stereo Song Assets ================== Defines a music track that can be played on the in-game stereo item. (Or any custom music player item for that matter.) For an example refer to ``Unturned_Theme.asset`` in the Songs folder. Asset Properties Reference -------------------------- **Type** *string*: ``SDG.Unturned.StereoSongAsset`` **Title** string: display text to show in the music player menu. If a localization .dat file is present the ``Name`` key will be used, or a translation reference can be used. Examples: .. code-block:: unturnedasset "Title" "My song" OR **Name** in {Language}.dat file OR .. code-block:: unturnedasset "Title" { "Namespace" "SDG" "Token" "Stereo_Songs.Unturned_Theme.Title" } **Song** :ref:`Master Bundle Pointer `: audio clip to play. Can either be a newer master bundle pointer or an older content pointer. Examples: .. code-block:: unturnedasset "Song" { "MasterBundle" "core.masterbundle" "AssetPath" "Effects/Ambience/Cave_0/Cave_0.ogg" } OR .. code-block:: unturnedasset "Song" { "Name" "core.content" "Path" "assets/resources/bundles/songs/unturned_theme.mp3" } **Link_URL** *string*: Optional URL to open in web browser when external link button is clicked. **Is_Loop** *bool*: Whether audio source should loop. Recommend **NOT** using .mp3 format for looping music. ================================================ FILE: assets/tag-asset.rst ================================================ .. _doc_assets_tag: Tag Assets ========== Although **tags** have some display properties, their primary purpose is to act as a unique identifier shared across multiple assets. This makes them especially useful for cross-mod compatibility. Currently, tags are used in two ways: 1. Workstation crafting capabilities. 2. Blueprint categorization. **GUID** *32-digit hexadecimal*: Refer to :ref:`doc_data_guid` documentation. **Type** ``Tag`` Tag Properties -------------- **NameColor** :ref:`color `: Optional override for color of name label in the user interface. **HasIcon** :ref:`bool `: If true, the game will expect an Icon texture in the asset bundle. Defaults to true. **IconPath** :ref:`Master Bundle Pointer `: Overrides where to load Icon texture from. **TintIcon** :ref:`bool `: If true, tints the icon according to player's foreground color preference. Defaults to true. Tinted icons are typically white #ffffff to fully change color. If your icons are colorful you may want to set this to false. Localization ------------ **Name** *string*: Display name in user interfaces. ================================================ FILE: assets/unity-upgrade.rst ================================================ .. _doc_unity_upgrade: Upgrading Unity Version ======================= This page covers the various engine upgrades that *Unturned* has undergone, and the important changes from them. While much of the older information is unlikely to still be relevant, it may provide some insight on the off chance that you are updating a particularly old mod, or referencing a tutorial created for a previous Unity version. From Unity 5 LTS to 2017 LTS ---------------------------- The upgrade from Unity 5.5 to 2017.4 was a large change, and any mods created in Unity 5 are no longer compatible with the game. For archival purposes, the Unity 5.5 LTS version of the game remains available from the "unity-5.5" beta branch. There were two key reasons for going through an engine upgrade. First, Unity 2017 marked the start of Unity's annual releases as they focused on stability, and performance could be improved by removing workarounds for some now-resolved Unity bugs. Second, Apple deprecated their OpenGL support, so supporting 2017.4's Metal graphics API would be important for macOS players. Master bundles were introduced to make updating mods easier. Master Bundles `````````````` Rather than exporting each bundle as individual .unity3d files, you can now export multiple bundles into a combined **.masterbundle**. Master bundles are not required, but they are more efficient when it comes to time and performance. However, they are not *required*, and you may find it easier to quickly iterate on a .unity3d bundle. If the game detects a master bundle file, it will load bundles from sub-directories using their relative folder path. For example, ``MyModBundles/Items/Guns/MyGunItem.dat`` could be the path to an item's .dat file. If ``MyModBundles`` contains a master bundle, it will try to load all Unity files using the relative path ``/Items/Guns``. It is important for .dat folders and Unity folders to line up, 1:1. Installing the Tools ```````````````````` Copy all of the files from ``Unturned/Bundles/Sources/Tools`` into the ``.../Assets/Editor`` directory of your Unity project. The **MasterBundleTool** will now be available from **Window > Unturned**. To use this tool, first assign your folder to an AssetBundle, and then export your bundles to a location that contains a corresponding MasterBundle.dat file. Shaders can be imported from the ``All_Shaders.unitypackage`` (also located in a subdirectory of ``Sources``). We recommend using official shaders to improve compatibility with base game content. Exporting from Unity ```````````````````` .. attention:: This section of the documentation is admittedly rather old, and it should eventually be moved to a better spot. Fortunately—these steps are still accurate, and the information below has been revised recently. *[2024 November]* Exporting requires some initial setup within Unity and the target location for your exported master bundle. In Unity, select the folder within the Project Browser that contains your bundles. Assign it to an AssetBundle from the Inspector. If you haven't created one yet, this is the time to do so. For example, vanilla/official bundles are in an AssetBundle named "core.masterbundle", while the curated Hawaii map's bundles are in "hawaii.masterbundle". Open the Master Bundle Tool. Select your AssetBundle from the dropdown. If your mod should be fully compatible with MacOS and Linux devices, you will need to check the "Multi-platform" option before exporting. .. tip:: When you're still working on your mod, you don't need to enable multi-platform support! This option can be toggled at any time. By only enabling this for release candidates, you can cut down on build time while you're still iterating. Clicking the "..." button will let you select a target location to export the master bundle into. Before you can proceed, you will need a MasterBundle.dat file in that location. Navigate to your target location. Any folder that would contain a master bundle needs a **MasterBundle.dat** file. When the game traverses the file hierarchy, it will check for this file, and if present it will assume all sub-folders should be redirected into that master bundle. Create this file at your target location. You should configure the following options in your MasterBundle.dat file: - | **Asset_Bundle_Name**: Filename of the Windows master bundle exported from Unity. For example, ``hawaii.masterbundle``. - | **Asset_Prefix**: Filepath to the folder you selected as an AssetBundle in Unity. For example, your path could be ``Assets/MyModBundles``. In which case, the game could look for an item in ``Assets/MyModBundles/Items/Guns``. .. note:: Bundled assets have a few optional properties they can use. The **Exclude_From_Master_Bundle** flag will cause that .dat file to ignore any parent MasterBundles in the folder hierarchy, and instead look for an individual .unity3d file. The **Master_Bundle_Override** property lets you specify the name of a master bundle to redirect to. **Bundle_Override_Path** can be used to have multiple items share the same setup in Unity (such as how the vanilla note objects share the same model), or combined with the previous property to use models from other master bundles (e.g., if you wanted to use the Eaglefire's model but give it custom stats). Back in Unity, you can now export your master bundle. Troubleshooting ``````````````` Colors too light or dark in-game ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Most likely the Color Space setting in your Unity project needs adjusting. Navigate to Edit > Project Settings > Player. Under the Other Settings section change Color Space to Linear. If that doesn't work, double-check that sRGB is enabled on your textures. Devkit Foliage ~~~~~~~~~~~~~~ Materials default to instancing disabled now, so enable the Instancing flag in the Unity material inspector and rebuild the asset bundle. From Unity 2017 LTS to 2018 LTS ------------------------------- For archival purposes, the Unity 2017.4 LTS version of the game remains available from the "unity-2017.4" beta branch. Asset Bundles ````````````` Older .unity3d/.content/.masterbundle files should work properly without needing any update unless they use custom shaders. The game automatically tries to consolidate their shaders with the latest versions during loading. Once re-exported, Asset_Bundle_Version can be set to 3 in MasterBundle.dat or individual .dat files to disable this shader consolidation step. Some of the slower asset checks like finding missing meshes have been made optional. Running the game with the "-ValidateAssets" command-line option enables them, and is recommended while working on new content. Unity Packages `````````````` All example content has been updated for 2018 LTS, and now has a consistent export process to ensure the contents are kept valid. What were once individual packages (e.g. All_Shaders.unitypackage) have been merged into a single ExampleAssets.unitypackage in the Extras/Sources/Examples directory. Logging / Server Console ```````````````````````` Usage of Unity's built-in Debug.Log has been replaced with logging to the Client.log or Server_XYZ.log files in the Logs folder. This works around conflict with standard output on the Linux server, so -logfile redirect workarounds should no longer be necessary. -ThreadedConsole implementation has been made the default, but can be disabled by -LegacyConsole. Workshop ```````` Uploads from 2018 LTS are incompatible with past versions of the game, and a warning message is shown when loading newer content in the 2017 LTS version. Platforms ````````` Linux 32-bit and MacOS 32-bit have been removed in favor of the 64-bit versions. Servers that were still using the outdated Linux 32-bit depot should update to the 64-bit Linux dedicated server. Headless server files have been removed from the player Linux depot, and are instead only in the dedicated server Linux depot. Windows headless mode is now supported in 2018 LTS, and is enabled for the Windows dedicated server depot. From Unity 2018 LTS to 2019 LTS ------------------------------- There are very few notable changes from this upgrade. For archival purposes, the Unity 2018 LTS version of the game remains available from the "unity-2018" beta branch. By default, Unity no longer supports importing multiple animations from a single .blend file. Exporting to an exchange format like .fbx is recommended. .. tip:: This is recommended for meshes/models as well! The base game has always handled its own assets like this, as well. You can find more details in `case #1186253 `_ on the Unity issue tracker. ================================================ FILE: assets/vehicle-asset.rst ================================================ .. _doc_assets_vehicle: Vehicle Assets ============== The **VehicleAsset** class is used by vehicles. These can be driven by players, have support for gun turrets, can function as a storage container for items, and more. Game Data File -------------- The ``GUID`` and ``Type`` properties are required by all vehicle assets. Many vehicle assets will want to include ``Engine`` and ``Rarity`` as well. The ``ID`` property used to be required, but this is no longer necessary. Any properties from parent classes that are required—or recommended—are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`Asset ` - :ref:`GUID ` - * - :ref:`Asset ` - :ref:`ID ` - * - :ref:`Asset ` - :ref:`Type ` - ``Vehicle`` * - :ref:`VehicleAsset ` - :ref:`Engine ` - Properties `````````` .. list-table:: Uncategorized :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`AdditionalTransparentSections ` - :ref:`list of PaintableVehicleSection ` - * - :ref:`Bicycle ` - :ref:`flag ` - * - :ref:`Bicycle_Anim_Speed ` - :ref:`float32 ` - ``0`` * - :ref:`Buildable_Placement_Rule ` - :ref:`EVehicleBuildablePlacementRule ` - ``None`` * - :ref:`Bypass_Hash_Verification ` - :ref:`flag ` - * - :ref:`Cam_Driver_Offset ` - :ref:`float32 ` - ``0`` * - :ref:`Cam_Follow_Distance ` - :ref:`float32 ` - ``5.5`` * - :ref:`Cam_Passenger_Offset ` - :ref:`float32 ` - ``0`` * - :ref:`Can_Be_Locked ` - :ref:`bool ` - ``true`` * - :ref:`Crawler ` - :ref:`flag ` - *deprecated* * - :ref:`CrawlerTrackTilingMaterials ` - :ref:`list of CrawlerTrackTilingMaterial ` - * - :ref:`Drops_Max ` - :ref:`uint8 ` - ``7`` * - :ref:`Drops_Min ` - :ref:`uint8 ` - ``3`` * - :ref:`Drops_Table_ID ` - :ref:`uint16 ` - ``962`` * - :ref:`Engine ` - :ref:`EEngine ` - ``Car`` * - :ref:`Exit ` - :ref:`float32 ` - ``2`` * - :ref:`GUID ` - :ref:`doc_data_guid` - * - :ref:`Has_Clip_Prefab ` - :ref:`bool ` - ``true`` * - :ref:`Has_Horn ` - :ref:`bool ` - See description * - :ref:`HornAudioClip ` - :ref:`Master Bundle Pointer ` - * - :ref:`ID ` - :ref:`uint16 ` - ``0`` * - :ref:`IgnitionAudioClip ` - :ref:`Master Bundle Pointer ` - * - :ref:`LockMouse ` - :ref:`flag ` - * - :ref:`Num_Steering_Tires ` - :ref:`int32 ` - *deprecated* * - :ref:`Rarity ` - :ref:`doc_data_eitemrarity` - ``Common`` * - :ref:`Reclined ` - :ref:`flag ` - * - :ref:`Should_Spawn_Seat_Capsules ` - :ref:`bool ` - ``false`` * - :ref:`Steering_Tire_# ` - :ref:`int32 ` - *deprecated* * - :ref:`Tire_ID ` - :ref:`uint16 ` - ``1451`` * - :ref:`Trunk_Storage_X ` - :ref:`uint8 ` - ``0`` * - :ref:`Trunk_Storage_Y ` - :ref:`uint8 ` - ``0`` * - :ref:`Valid_Speed_Down ` - :ref:`float32 ` - * - :ref:`Valid_Speed_Horizontal ` - :ref:`float32 ` - * - :ref:`Valid_Speed_Up ` - :ref:`float32 ` - * - :ref:`Zip ` - :ref:`flag ` - .. list-table:: Handling :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Air_Steer_Max ` - :ref:`float32 ` - See description * - :ref:`Air_Steer_Min ` - :ref:`float32 ` - See description * - :ref:`Air_Turn_Responsiveness ` - :ref:`float32 ` - ``2`` * - :ref:`Brake ` - :ref:`float32 ` - * - :ref:`Center_Of_Mass ` - :ref:`vector3 ` - * - :ref:`Carjack_Force_Multiplier ` - :ref:`float32 ` - ``1.0`` * - :ref:`CrawlerTrackSteering_Torque ` - :ref:`float32 ` - ``0.0`` * - :ref:`CrawlerTrackSteering_SidewaysFrictionMultiplier ` - :ref:`float32 ` - ``1.0`` * - :ref:`CrawlerTrackSteering_MaxSpeedScale ` - :ref:`float32 ` - ``1.0`` * - :ref:`Engine_Force_Multiplier ` - :ref:`float32 ` - ``1.0`` * - :ref:`Lift ` - :ref:`float32 ` - ``0`` * - :ref:`Override_Center_Of_Mass ` - :ref:`bool ` - ``false`` * - :ref:`Physics_Profile ` - :ref:`GUID ` - See description * - :ref:`RollAngularVelocityDamping ` - :ref:`float32 ` - ``-1.0`` * - :ref:`Sleds ` - :ref:`flag ` - * - :ref:`Speed_Max ` - :ref:`float32 ` - ``0`` * - :ref:`Speed_Min ` - :ref:`float32 ` - ``0`` * - :ref:`Steering_Angle_FullSpeed_Factor ` - :ref:`float32 ` - ``0`` * - :ref:`Steering_Angle_Max ` - :ref:`float32 ` - ``0`` * - :ref:`Steering_Angle_Turn_Speed ` - :ref:`float32 ` - See description * - :ref:`Steering_LeaningForceMultiplier ` - :ref:`float32 ` - ``-1.0`` * - :ref:`Steering_LeaningForce_ScaleWithSpeed ` - :ref:`bool ` - ``false`` * - :ref:`Steering_LeaningForce_SpeedExponent ` - :ref:`float32 ` - ``1.0`` * - :ref:`Traction ` - :ref:`flag ` - * - :ref:`Wheel_Collider_Mass_Override ` - :ref:`float32 ` - ``null`` * - :ref:`WheelBalancing_ForceMultiplier ` - :ref:`float32 ` - ``-1.0`` * - :ref:`WheelBalancing_UprightExponent ` - :ref:`float32 ` - ``1.5`` * - :ref:`WheelConfigurations ` - :ref:`list of VehicleWheelConfiguration ` - .. list-table:: Engine RPM and Gears :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`EngineIdleRPM ` - :ref:`float32 ` - ``1000.0`` * - :ref:`EngineMaxRPM ` - :ref:`float32 ` - ``7000.0`` * - :ref:`EngineMaxTorque ` - :ref:`float32 ` - ``1.0`` * - :ref:`EngineRPM_DecreaseRate ` - :ref:`float32 ` - ``-1.0`` * - :ref:`EngineRPM_IncreaseRate ` - :ref:`float32 ` - ``-1.0`` * - :ref:`EngineRPMMismatch_TorqueReduction_Enabled ` - :ref:`bool ` - ``false`` * - :ref:`EngineRPMMismatch_TorqueReduction_Threshold ` - :ref:`float ` - ``0.0`` * - :ref:`EngineRPMMismatch_GearShift_PreventShifting ` - :ref:`bool ` - ``false`` * - :ref:`EngineRpmMismatch_GearShift_UpMinThreshold ` - :ref:`float ` - ``0.0`` * - :ref:`EngineRpmMismatch_GearShift_UpMaxThreshold ` - :ref:`float ` - ``0.0`` * - :ref:`EngineRpmMismatch_GearShift_DownMinThreshold ` - :ref:`float ` - ``0.0`` * - :ref:`EngineRpmMismatch_GearShift_DownMaxThreshold ` - :ref:`float ` - ``0.0`` * - :ref:`ForwardGearRatios ` - :ref:`list of float32 ` - * - :ref:`GearShift_AllowSkippingGears ` - :ref:`bool ` - ``true`` * - :ref:`GearShift_DownThresholdRPM ` - :ref:`float32 ` - ``1500.0`` * - :ref:`GearShift_Duration ` - :ref:`float32 ` - ``0.5`` * - :ref:`GearShift_Interval ` - :ref:`float32 ` - ``1.0`` * - :ref:`GearShift_UpThresholdRPM ` - :ref:`float32 ` - ``5500.0`` * - :ref:`GearShift_VisibleInHUD ` - :ref:`bool ` - ``true`` * - :ref:`ReverseGearRatio ` - :ref:`float32 ` - ``1.0`` .. list-table:: Engine Sound :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`EngineSound ` - :ref:`RpmEngineSoundConfiguration ` - * - :ref:`EngineSound_Type ` - :ref:`EVehicleEngineSoundType ` - ``Legacy`` * - :ref:`Pitch_Drive ` - :ref:`float32 ` - * - :ref:`Pitch_Idle ` - :ref:`float32 ` - .. list-table:: Health and Armor :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Bumper_AnimalDamage ` - :ref:`float32 ` - ``15.0`` * - :ref:`Bumper_Invulnerable ` - :ref:`flag ` - * - :ref:`Bumper_Multiplier ` - :ref:`float32 ` - ``1.0`` * - :ref:`Bumper_ObjectDamage ` - :ref:`float32 ` - ``30.0`` * - :ref:`Bumper_PlayerDamage ` - :ref:`float32 ` - ``10.0`` * - :ref:`Bumper_ResourceDamage ` - :ref:`float32 ` - ``85.0`` * - :ref:`Bumper_SelfDamageMultiplier ` - :ref:`float32 ` - ``1.0`` * - :ref:`Bumper_SpeedDamageThreshold ` - :ref:`float32 ` - ``3.0`` * - :ref:`Bumper_ZombieDamage ` - :ref:`float32 ` - ``15.0`` * - :ref:`Can_Repair_While_Seated ` - :ref:`bool ` - ``false`` * - :ref:`Child_Explosion_Armor_Multiplier ` - :ref:`float32 ` - ``0.2`` * - :ref:`Environment_Invulnerable ` - :ref:`flag ` - * - :ref:`Explosions_Invulnerable ` - :ref:`flag ` - * - :ref:`Health ` - :ref:`uint16 ` - ``0`` * - :ref:`Health_Max ` - :ref:`uint16 ` - ``0`` * - :ref:`Health_Min ` - :ref:`uint16 ` - ``0`` * - :ref:`Invulnerable ` - :ref:`flag ` - * - :ref:`Passenger_Explosion_Armor ` - :ref:`float32 ` - ``1`` * - :ref:`Tires_Invulnerable ` - :ref:`flag ` - .. list-table:: Fuel :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Fuel ` - :ref:`uint16 ` - ``0`` * - :ref:`Fuel_Burn_Rate ` - :ref:`float32 ` - See description * - :ref:`Fuel_Min ` - :ref:`uint16 ` - ``0`` * - :ref:`Fuel_Max ` - :ref:`uint16 ` - ``0`` .. list-table:: Battery :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Battery_Burn_Rate ` - :ref:`float32 ` - ``20`` * - :ref:`Battery_Charge_Rate ` - :ref:`float32 ` - ``20`` * - :ref:`Battery_Powered ` - :ref:`flag ` - * - :ref:`Battery_Spawn_Charge_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`BatteryMode_Driving ` - :ref:`doc_data_ebatterymode` - ``Charge`` * - :ref:`BatteryMode_Empty ` - :ref:`doc_data_ebatterymode` - ``None`` * - :ref:`BatteryMode_Headlights ` - :ref:`doc_data_ebatterymode` - ``Burn`` * - :ref:`BatteryMode_Sirens ` - :ref:`doc_data_ebatterymode` - ``Burn`` * - :ref:`Can_Steal_Battery ` - :ref:`bool ` - ``true`` * - :ref:`Cannot_Spawn_With_Battery ` - :ref:`flag ` - * - :ref:`Default_Battery ` - :ref:`doc_data_guid` - ``098b13be34a7411db7736b7f866ada69`` .. list-table:: Stamina :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Stamina_Boost ` - :ref:`float32 ` - * - :ref:`Stamina_Powered ` - :ref:`flag ` - .. list-table:: Paintability :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`DefaultPaintColor_Configuration ` - :ref:`VehicleRandomPaintColorConfiguration ` - * - :ref:`DefaultPaintColor_Mode ` - :ref:`EVehicleDefaultPaintColorMode ` - See description * - :ref:`DefaultPaintColors ` - :ref:`list of colors ` - * - :ref:`IsPaintable ` - :ref:`bool ` - * - :ref:`PaintableSections ` - :ref:`list of PaintableVehicleSection ` - .. list-table:: Explosion :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Explosion ` - :ref:`GUID ` or :ref:`uint16 ` - * - :ref:`ExplosionBurnMaterialSections ` - :ref:`list of PaintableVehicleSection ` - * - :ref:`Explosion_Force_Multiplier ` - :ref:`float32 ` - ``1.0`` * - :ref:`Explosion_Max_Force ` - :ref:`vector3 ` - ``(0, 1024, 0)`` * - :ref:`Explosion_Min_Force ` - :ref:`vector3 ` - ``(0, 1024, 0)`` * - :ref:`ShouldExplosionBurnMaterials ` - :ref:`bool ` - See description * - :ref:`ShouldExplosionCauseDamage ` - :ref:`bool ` - See description .. list-table:: Turret :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Turret_#_Ignore_Aim_Camera ` - :ref:`flag ` - * - :ref:`Turret_#_Item_ID ` - :ref:`uint16 ` - ``0`` * - :ref:`Turret_#_Pitch_Max ` - :ref:`float32 ` - ``0`` * - :ref:`Turret_#_Pitch_Min ` - :ref:`float32 ` - ``0`` * - :ref:`Turret_#_Seat_Index ` - :ref:`uint8 ` - ``0`` * - :ref:`Turret_#_Yaw_Max ` - :ref:`float32 ` - ``0`` * - :ref:`Turret_#_Yaw_Min ` - :ref:`float32 ` - ``0`` * - :ref:`Turrets ` - :ref:`uint8 ` - ``0`` .. list-table:: Train :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Train_Car_Length ` - :ref:`float32 ` - ``0`` * - :ref:`Train_Track_Offset ` - :ref:`float32 ` - ``0`` * - :ref:`Train_Wheel_Offset ` - :ref:`float32 ` - ``0`` .. list-table:: Economy :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Shared_Skin_Lookup_ID ` - :ref:`doc_data_guid` or :ref:`uint16 ` - See description * - :ref:`Shared_Skin_Name ` - :ref:`string ` - * - :ref:`Size2_Z ` - :ref:`float32 ` - ``0`` .. _doc_assets_vehicle:eengine: EEngine Enumeration ``````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``Car`` - This vehicle is part of the Car category. * - ``Plane`` - This vehicle is part of the Plane category. * - ``Blimp`` - This vehicle is part of the Blimp category. * - ``Boat`` - This vehicle is part of the Boat category. * - ``Train`` - This vehicle is part of the Train category. .. _doc_assets_vehicle:evehiclebuildableplacementrule: EVehicleBuildablePlacementRule Enumeration `````````````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - Vehicle does not override placement. This means that barricades can be attached *unless* the barricade sets :ref:`Allow_Placement_On_Vehicle ` to ``false`` (e.g., beds and sentry guns are often set to ``false``). * - ``AlwaysAllow`` - Vehicle allows any barricade to be placed on it, regardless of the barricade's :ref:`Allow_Placement_On_Vehicle ` setting. Trains used to use this option, but it can be exploited to move beds into out-of-bounds areas (e.g., into other objects). * - ``Block`` - Vehicle prevents any barricade form being placed on it. .. _doc_assets_vehicle:evehicledefaultpaintcolormode: EVehicleDefaultPaintColorMode ````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - Not configured. * - ``List`` - Pick from the :ref:`DefaultPaintColors ` list. * - ``RandomHueOrGrayscale`` - Pick a random HSV using :ref:`DefaultPaintColor_Configuration `. .. _doc_assets_vehicle:evehicleenginesoundtype: EVehicleEngineSoundType Enumeration ``````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``Legacy`` - Default. * - ``EngineRPMSimple`` - Set pitch and volume of a single clip according to engine RPM. .. _doc_assets_vehicle:ewheelmotioneffectsmode: EWheelMotionEffectsMode Enumeration ``````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - Turn off motion effects. Default for wheels not using collider pose. * - ``BothDirections`` - Enable motion effects. Default for wheels using collider pose. * - ``ForwardOnly`` - Enable motion effects, but turn them off while moving backward. * - ``BackwardOnly`` - Enable motion effects, but turn them off while moving forward. .. _doc_assets_vehicle:ewheelsteeringmode: EWheelSteeringMode Enumeration `````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - Wheel does not affect steering. * - ``SteeringAngle`` - Set WheelCollider steering angle according to Steer_Min and Steer_Max. * - ``CrawlerTrack`` - Increase or decrease motor torque to rotate vehicle in-place. .. _doc_assets_vehicle:ecrawlertrackforwardmode: ECrawlerTrackForwardMode Enumeration ```````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``Auto`` - Assigns a forward mode based on wheel collider position. Wheels on the left side are ``Clockwise`` and wheels on the right side are ``CounterClockwise``. * - ``Clockwise`` - Positive motor torque on this wheel rotates the vehicle clockwise. * - ``CounterClockwise`` - Positive motor torque on this wheel rotates the vehicle counter-clockwise. .. _doc_assets_vehicle:crawlertracktilingmaterial_dictionary: CrawlerTrackTilingMaterial Dictionary ````````````````````````````````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Path ` - :ref:`string ` - * - :ref:`MaterialIndex ` - :ref:`int32 ` - ``0`` * - :ref:`WheelIndices ` - :ref:`list of int32 ` - * - :ref:`RepeatDistance ` - :ref:`float32 ` - ``0.0`` * - :ref:`UV_Direction ` - :ref:`Vector2 ` - ``(0.0, 0.0)`` .. _doc_assets_vehicle:paintablevehiclesection_dictionary: PaintableVehicleSection Dictionary `````````````````````````````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Path ` - :ref:`string ` - * - :ref:`MaterialIndex ` - :ref:`int32 ` - ``0`` * - :ref:`AllMaterials ` - :ref:`bool ` - ``false`` .. _doc_assets_vehicle:rpmenginesoundconfiguration_dictionary: RpmEngineSoundConfiguration Dictionary `````````````````````````````````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`IdlePitch ` - :ref:`float32 ` - ``0.0`` * - :ref:`IdleVolume ` - :ref:`float32 ` - ``0.0`` * - :ref:`MaxPitch ` - :ref:`float32 ` - ``0.0`` * - :ref:`MaxVolume ` - :ref:`float32 ` - ``0.0`` .. _doc_assets_vehicle:vehiclerandompaintcolorconfiguration_dictionary: VehicleRandomPaintColorConfiguration Dictionary ``````````````````````````````````````````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`MinSaturation ` - :ref:`float32 ` - ``0.0`` * - :ref:`MaxSaturation ` - :ref:`float32 ` - ``0.0`` * - :ref:`MinValue ` - :ref:`float32 ` - ``0.0`` * - :ref:`MaxValue ` - :ref:`float32 ` - ``0.0`` * - :ref:`GrayscaleChance ` - :ref:`float32 ` - ``0.0`` .. _doc_assets_vehicle:vehiclewheelconfiguration_dictionary: VehicleWheelConfiguration Dictionary ```````````````````````````````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`CanExplode ` - :ref:`bool ` - ``true`` * - :ref:`CopyColliderRpmIndex ` - :ref:`int32 ` - ``-1`` * - :ref:`CrawlerTrackForwardMode ` - :ref:`doc_assets_vehicle:ecrawlertrackforwardmode` - ``Auto`` * - :ref:`IsColliderPowered ` - :ref:`bool ` - ``false`` * - :ref:`IsModelSteered ` - :ref:`bool ` - ``false`` * - :ref:`ModelPath ` - :ref:`string ` - * - :ref:`ModelRadius ` - :ref:`float32 ` - ``-1.0`` * - :ref:`ModelSuspensionOffset ` - :ref:`float32 ` - ``0.0`` * - :ref:`ModelSuspensionSpeed ` - :ref:`float32 ` - ``-1.0`` * - :ref:`ModelUseColliderPose ` - :ref:`bool ` - ``false`` * - :ref:`MotionEffects ` - :ref:`doc_assets_vehicle:ewheelmotioneffectsmode` - See description * - :ref:`SteeringAngleMultiplier ` - :ref:`float32 ` - ``1.0`` * - :ref:`SteeringMode ` - :ref:`doc_assets_vehicle:ewheelsteeringmode` - ``None`` * - :ref:`WheelColliderPath ` - :ref:`string ` - Property Descriptions ````````````````````` .. _doc_assets_vehicle:additionaltransparentsections: AdditionalTransparentSections :ref:`list of PaintableVehicleSection ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Materials to register as needing transparent sorting. Their render queue is periodically updated according to whether their pivot point is underwater. ---- .. _doc_assets_vehicle:air_steer_max: Air_Steer_Max :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: The angle to turn when moving quickly, when using ``Engine Plane``. Defaults to the value of ``Steer_Max``. ---- .. _doc_assets_vehicle:air_steer_min: Air_Steer_Min :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: The angle to turn when moving slowly, when using ``Engine Plane``. Defaults to the value of ``Steer_Min``. ---- .. _doc_assets_vehicle:air_turn_responsiveness: Air_Turn_Responsiveness :ref:`float32 ` ``2`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Sensitivity on steering while airborne, when using ``Engine Plane``. ---- .. _doc_assets_vehicle:battery_burn_rate: Battery_Burn_Rate :ref:`float32 ` ``20`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This controls the rate at which battery charge decreases per second. ---- .. _doc_assets_vehicle:battery_charge_rate: Battery_Charge_Rate :ref:`float32 ` ``20`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This controls the rate at which battery charge increases per second. ---- .. _doc_assets_vehicle:battery_powered: Battery_Powered :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::: The vehicle does not use fuel. For example, this flag is useful for creating electric vehicles. ---- .. _doc_assets_vehicle:battery_spawn_charge_multiplier: Battery_Spawn_Charge_Multiplier :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Battery charge on a newly-spawned vehicle is multiplied by this [0, 1] number. Setting this to a number less than ``1`` will result in the vehicle spawning with less battery charge than normal. ---- .. _doc_assets_vehicle:batterymode_driving: BatteryMode_Driving :ref:`doc_data_ebatterymode` ``Charge`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How the vehicle battery should behave when a player is driving it. ---- .. _doc_assets_vehicle:batterymode_empty: BatteryMode_Empty :ref:`doc_data_ebatterymode` ``None`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How the vehicle battery should behave when the vehicle is empty. ---- .. _doc_assets_vehicle:batterymode_headlights: BatteryMode_Headlights :ref:`doc_data_ebatterymode` ``Burn`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How the vehicle battery should behave when the headlights are on. ---- .. _doc_assets_vehicle:batterymode_sirens: BatteryMode_Sirens :ref:`doc_data_ebatterymode` ``Burn`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How the vehicle battery should behave when the siren is on. ---- .. _doc_assets_vehicle:bicycle: Bicycle :ref:`flag ` ::::::::::::::::::::::::::::::::::: Player character should use a bicycling animation. ---- .. _doc_assets_vehicle:bicycle_anim_speed: Bicycle_Anim_Speed :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the speed of the bicycling animation. ---- .. _doc_assets_vehicle:brake: Brake :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::: The amount of braking force to apply. ---- .. _doc_assets_vehicle:buildable_placement_rule: Buildable_Placement_Rule :ref:`EVehicleBuildablePlacementRule ` ``None`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This property overrides how barricades can be attached to the vehicle. View the :ref:`EVehicleBuildablePlacementRule ` documentation for more information about the behavior of each option. Note that the ``Bypass_Buildable_Mobility`` gameplay config option, when ``true``, will always take priority over this property. The ``Supports_Mobile_Buildables`` flag predates this property, and has since been deprecated. Its behavior can be replicated by using this property with the ``AlwaysAllow`` value instead. ---- .. _doc_assets_vehicle:bumper_animaldamage: Bumper_AnimalDamage :ref:`float32 ` ``15`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Base damage to animals when traveling at 1 m/s (before speed and other multipliers apply). ---- .. _doc_assets_vehicle:bumper_invulnerable: Bumper_Invulnerable :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::::::: The vehicle cannot be damaged by collisions (such as with other vehicles, objects, placeables, or entities). ---- .. _doc_assets_vehicle:bumper_multiplier: Bumper_Multiplier :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplies vehicle speed (in m/s) at time of collision. If result is less than ``Bumper_SpeedDamageThreshold``, no damage is applied. The multiplied speed is applied to outgoing damage. For example: if speed is 4 m/s with a ``Bumper_Multiplier`` of 2 and a base damage of 10, 80 damage is applied. ---- .. _doc_assets_vehicle:bumper_objectdamage: Bumper_ObjectDamage :ref:`float32 ` ``30`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Base damage to objects when traveling at 1 m/s (before speed and other multipliers apply). ---- .. _doc_assets_vehicle:bumper_playerdamage: Bumper_PlayerDamage :ref:`float32 ` ``10`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Base damage to players when traveling at 1 m/s (before speed and other multipliers apply). ---- .. _doc_assets_vehicle:bumper_resourcedamage: Bumper_ResourceDamage :ref:`float32 ` ``85`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Base damage to resources when traveling at 1 m/s (before speed and other multipliers apply). ---- .. _doc_assets_vehicle:bumper_selfdamagemultiplier: Bumper_SelfDamageMultiplier :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier for damage inflicted to the vehicle by crashing into things. Not applicable if the ``Bumper_Invulnerable`` flag is applied. ---- .. _doc_assets_vehicle:bumper_speeddamagethreshold: Bumper_SpeedDamageThreshold :ref:`float32 ` ``3.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If speed (in m/s) multiplied by ``Bumper_Multiplier`` is less than this threshold, no damage is applied. ---- .. _doc_assets_vehicle:bumper_zombiedamage: Bumper_ZombieDamage :ref:`float32 ` ``15`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Base damage to zombies when traveling at 1 m/s (before speed and other multipliers apply). ---- .. _doc_assets_vehicle:bypass_hash_verification: Bypass_Hash_Verification :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::::::::: Disable hash verification check, and allow for mismatched files. ---- .. _doc_assets_vehicle:cam_driver_offset: Cam_Driver_Offset :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The vertical offset for the driver's first-person camera, in meters. This is additive with the value of ``Cam_Passenger_Offset``. ---- .. _doc_assets_vehicle:cam_follow_distance: Cam_Follow_Distance :ref:`float32 ` ``5.5`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The distance behind the player the third-person camera should be placed at, in meters. ---- .. _doc_assets_vehicle:cam_passenger_offset: Cam_Passenger_Offset :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The vertical offset for any passenger's (including the driver's) first-person camera, in meters. ---- .. _doc_assets_vehicle:can_be_locked: Can_Be_Locked :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Whether or not the vehicle can be locked by a player. ---- .. _doc_assets_vehicle:can_repair_while_seated: Can_Repair_While_Seated :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, this vehicle can be repaired by seated players. ---- .. _doc_assets_vehicle:can_steal_battery: Can_Steal_Battery :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Whether or not the vehicle battery can be removed from the vehicle by a player. ---- .. _doc_assets_vehicle:cannot_spawn_with_battery: Cannot_Spawn_With_Battery :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: The vehicle does not spawn with a vehicle battery. ---- .. _doc_assets_vehicle:carjack_force_multiplier: Carjack_Force_Multiplier :ref:`float32 ` ``1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This is a multiplier on the force applied when using a `Carjack `_ on this vehicle. It is recommended that this property scales based on your vehicle's mass. Although this property was originally intended for modded vehicles, many official vehicles use this property as well. If you are creating a custom vehicle and using one of the example assets provided as a template (or have a mass that is similar to official content), you will likely want to use a value of ``2`` for this property. The mass of official vehicles may be revisited in the future, to make collisions feel more reasonable. If this happens, the recommended value could be increased again. ---- .. _doc_assets_vehicle:crawlertracksteering_torque: CrawlerTrackSteering_Torque :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Added or subtracted from wheel motor torque in ``CrawlerTrack`` mode. For example, if the vehicle is attempting to turn left and the wheel's ``CrawlerTrackForwardMode`` is ``Clockwise`` this value is subtracted from the motor torque. ---- .. _doc_assets_vehicle:crawlertracksteering_sidewaysfrictionmultiplier: CrawlerTrackSteering_SidewaysFrictionMultiplier :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: For a wheel in ``CrawlerTrack`` mode, the wheel collider's sideways friction stiffness is multiplied by this value while a steering input is applied. Potentially useful when turning in place to overcome the sideways friction. ---- .. _doc_assets_vehicle:crawlertracksteering_maxspeedscale: CrawlerTrackSteering_MaxSpeedScale :ref:`float32 ` ``1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier for crawler track steering torque and sideways friction multiplier while driving at maximum speed, similar to how steering angle is reduced at maximum speed (``Steer_Max``). Useful to keep the steering controllable while driving. ---- .. _doc_assets_vehicle:crawlertracktilingmaterials: CrawlerTrackTilingMaterials :ref:`list of CrawlerTrackTilingMaterial ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If set, offsets a crawler track's material UVs in sync with wheels rolling. ---- .. _doc_assets_vehicle:center_of_mass: Center_Of_Mass :ref:`vector3 ` :::::::::::::::::::::::::::::::::::::::::::::::: Overrides the vehicle's center of mass on the 𝘟\-, 𝘠\-, and 𝘡-axis, when using ``Override_Center_Of_Mass true``. This allows for modifying a vehicle's center of gravity without needing to move the "Cog" GameObject in Unity. For example: .. code-block:: unturneddat :linenos: Override_Center_Of_Mass true Center_Of_Mass (0, -50, 0) ---- .. _doc_assets_vehicle:child_explosion_armor_multiplier: Child_Explosion_Armor_Multiplier :ref:`float32 ` ``0.2`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This is a multiplier on the damage that barricades (and other buildables) placed on the vehicle receive, when damaged by explosions. ---- .. _doc_assets_vehicle:crawler: Crawler :ref:`flag ` ::::::::::::::::::::::::::::::::::: .. deprecated:: 3.23.4.0 Replaced by the ``WheelConfigurations`` property. Disables the ``Wheel_#`` GameObjects from turning when steering by setting the default value of ``Num_Steering_Tires`` to ``0``. This property has no effect if ``Num_Steering_Tires`` has been manually set. ---- .. _doc_assets_vehicle:default_battery: Default_Battery :ref:`doc_data_guid` ``098b13be34a7411db7736b7f866ada69`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Battery item given to the player when a specific battery hasn't been manually installed yet. Defaults to the `Vehicle Battery `_ used by official vehicles. ---- .. _doc_assets_vehicle:defaultpaintcolor_configuration: DefaultPaintColor_Configuration :ref:`VehicleRandomPaintColorConfiguration ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Determines the potential colors of a newly-spawned vehicle. Can be overridden by a :ref:`Vehicle Redirector `'s :ref:`LoadPaintColor ` and :ref:`LoadPaintColor ` properties. This property is used with ``DefaultPaintColor_Mode RandomHueOrGrayscale``. For example: .. code-block:: unturneddat :linenos: DefaultPaintColor_Mode RandomHueOrGrayscale DefaultPaintColor_Configuration { MinSaturation 0.15 MaxSaturation 0.7 MinValue 0.15 MaxValue 0.9 GrayscaleChance 0.1 } ---- .. _doc_assets_vehicle:defaultpaintcolor_mode: DefaultPaintColor_Mode :ref:`EVehicleDefaultPaintColorMode ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This property controls the mode that should be used when randomly picking a paint color for a newly-spawned vehicle. Defaults to ``List`` if :ref:`DefaultPaintColors ` has been configured. Otherwise, defaults to ``None``. This can be manually set to ``RandomHueOrGrayscale`` to pick a random HSV. ---- .. _doc_assets_vehicle:defaultpaintcolors: DefaultPaintColors :ref:`list of colors ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: List of random colors to pick from when spawning a new vehicle. Can be overridden by a :ref:`Vehicle Redirector `'s :ref:`LoadPaintColor ` and :ref:`LoadPaintColor ` properties. This property is used with ``DefaultPaintColor_Mode List``. For example: .. code-block:: unturneddat :linenos: DefaultPaintColor_Mode List DefaultPaintColors [ "#353535" // Classic Black "#37658c" // Classic Blue "#2e642e" // Classic Green "#bd6e27" // Classic Orange "#6a466d" // Classic Purple "#9a2525" // Classic Red "#d4d4d4" // Classic White "#cdaa1e" // Classic Yellow ] ---- .. _doc_assets_vehicle:drops_max: Drops_Max :ref:`uint8 ` ``7`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum amount of item drops to spawn when the vehicle is destroyed. ---- .. _doc_assets_vehicle:drops_min: Drops_Min :ref:`uint8 ` ``3`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum amount of item drops to spawn when the vehicle is destroyed. ---- .. _doc_assets_vehicle:drops_table_id: Drops_Table_ID :ref:`uint16 ` ``962`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ID of the item spawn table to use when the vehicle is destroyed. The default spawn table is Destroyed_Vehicle_Default. ---- .. _doc_assets_vehicle:engine: Engine :ref:`EEngine ` ``Car`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The ``Engine`` property determines the type of vehicle (e.g., car, plane, boat). Some vehicle properties are only usable depending on the vehicle's ``Engine``. ---- .. _doc_assets_vehicle:engine_force_multiplier: Engine_Force_Multiplier :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This is a multiplier on otherwise not-yet-configurable plane/heli/boat/etc. forces. It is recommended that this property scales based on your vehicle's mass. ---- .. _doc_assets_vehicle:enginemaxtorque: EngineMaxTorque :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier for the amount of torque provided to the wheels. Understanding how engine RPM is translated to wheel torque is crucial for tuning the physics: #. Engine RPM is normalized into a 0 to 1 range according to :ref:`EngineIdleRPM ` and :ref:`EngineMaxRPM `. For example, an Engine RPM of 2000 with Idle RPM of 1000 and Max RPM of 5000 would be 0.25. #. Vehicle root needs an ``EngineCurvesComponent`` attached. This allows you to map normalized engine RPM to a normalized torque multiplier. Typically, the multiplier should be closest to 1 in the middle range (e.g., 0.3 to 0.8) and drop off toward 0 and 1. #. Torque curve is sampled using the normalized engine RPM. #. Sampled torque is multiplied by ``EngineMaxTorque``. #. If changing gears, torque is zero. #. If reversing, torque is multiplied by :ref:`ReverseGearRatio `. #. Otherwise, torque is multiplied by the active :ref:`ForwardGearRatio `. #. Each :ref:`Powered Wheel ` gets an equal share of the torque. To clarify, the per-wheel torque is equal to the engine output torque divided by the number of powered wheels. ---- .. _doc_assets_vehicle:enginerpm_decreaserate: EngineRPM_DecreaseRate :ref:`float32 ` ``-1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How quickly engine RPM can decrease in RPM/s. For example, 1000 will take 2 seconds to go from 4000 to 2000 RPM. Defaults to -1 which instantly changes RPM. .. note:: Originally, I thought this might come in handy, but in practice tuning the torque and gear ratios worked better. Kept in case it comes in useful for somebody. ---- .. _doc_assets_vehicle:enginesound: EngineSound :ref:`RpmEngineSoundConfiguration ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When :ref:`EngineSound_Type ` is set to ``EngineRPMSimple``, this should be set to an :ref:`RpmEngineSoundConfiguration dictionary `. ---- .. _doc_assets_vehicle:enginesound_type: EngineSound_Type :ref:`EVehicleEngineSoundType ` ``Legacy`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Defaults to ``Legacy``. In that mode, ``Pitch_Idle`` and ``Pitch_Drive`` are used to control engine audio pitch. ---- .. _doc_assets_vehicle:engineidlerpm: EngineIdleRPM :ref:`float32 ` ``1000.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Engine RPM will never drop below this value regardless of whether wheel RPM * gear ratio is lower. Otherwise, the engine wouldn't be able to start the wheels rolling from zero. ---- .. _doc_assets_vehicle:enginerpm_increaserate: EngineRPM_IncreaseRate :ref:`float32 ` ``-1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How quickly engine RPM can increase in RPM/s. For example, 1000 will take 2 seconds to go from 2000 to 4000 RPM. Defaults to -1 which instantly changes RPM. .. note:: Originally, I thought this might come in handy, but in practice tuning the torque and gear ratios worked better. Kept in case it comes in useful for somebody. ---- .. _doc_assets_vehicle:enginerpmmismatch_torquereduction_enabled: EngineRPMMismatch_TorqueReduction_Enabled :ref:`float32 ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, wheel RPM is reduced according to the difference between expected and actual wheel RPM divided by torque reduction threshold. ---- .. _doc_assets_vehicle:enginerpmmismatch_torquereduction_threshold: EngineRPMMismatch_TorqueReduction_Threshold :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If torque reduction is enabled, torque is reduced to zero when difference between expected and actual RPM is greater than this threshold. For non-linear reduction, you can enable **Use Engine RPM Mismatch Torque Reduction Curve** on the Engine Curves Component. ---- .. _doc_assets_vehicle:enginerpmmismatch_gearshift_preventshifting: EngineRPMMismatch_GearShift_PreventShifting :ref:`float32 ` ``-1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, prevent changing gears when the difference between expected and actual wheel RPM exceeds threshold. ---- .. _doc_assets_vehicle:enginerpmmismatch_gearshift_upminthreshold: EngineRpmMismatch_GearShift_UpMinThreshold :ref:`float32 ` ``0.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If prevent shifting is enabled, prevent changing gears up when the difference between expected and actual wheel RPM is less than this threshold. I.e., if ``expected - actual < min`` it cannot shift up. ---- .. _doc_assets_vehicle:enginerpmmismatch_gearshift_upmaxthreshold: EngineRpmMismatch_GearShift_UpMaxThreshold :ref:`float32 ` ``0.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If prevent shifting is enabled, prevent changing gears up when the difference between expected and actual wheel RPM is greater than this threshold. I.e., if ``expected - actual > max`` it cannot shift up. ---- .. _doc_assets_vehicle:enginerpmmismatch_gearshift_downminthreshold: EngineRpmMismatch_GearShift_DownMinThreshold :ref:`float32 ` ``0.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If prevent shifting is enabled, prevent changing gears down when the difference between expected and actual wheel RPM is less than this threshold. I.e., if ``expected - actual < min`` it cannot shift down. ---- .. _doc_assets_vehicle:enginerpmmismatch_gearshift_downmaxthreshold: EngineRpmMismatch_GearShift_DownMaxThreshold :ref:`float32 ` ``0.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If prevent shifting is enabled, prevent changing gears down when the difference between expected and actual wheel RPM is greater than this threshold. I.e., if ``expected - actual > max`` it cannot shift down. ---- .. _doc_assets_vehicle:enginemaxrpm: EngineMaxRPM :ref:`float32 ` ``7000.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Engine RPM will never exceed this value regardless of whether wheel RPM * gear ratio is higher. It should be kept to a reasonable value because the normalized engine RPM is used in a variety of places like sampling the torque curve and network replication. ---- .. _doc_assets_vehicle:environment_invulnerable: Environment_Invulnerable :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::::::::: This vehicle cannot be damaged by animals, zombie melee attacks, or boulders thrown by mega zombies. Zombies and animals will still pursue the vehicle, and attempt to attack any passengers directly. Other damage sources can still damage the vehicle. ---- .. _doc_assets_vehicle:exit: Exit :ref:`float ` ``2`` :::::::::::::::::::::::::::::::::::::::::::::::: Distance away from the vehicle to teleport when exiting. ---- .. _doc_assets_vehicle:explosion: Explosion :ref:`doc_data_guid` or :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of :ref:`EffectAsset ` to play when destroyed. ---- .. _doc_assets_vehicle:explosion_force_multiplier: Explosion_Force_Multiplier :ref:`float32 ` ``1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This is a multiplier on the force applied when the vehicle explodes. It is recommended that this property scales based on your vehicle's mass. Many official vehicles use this property. If you are creating a custom vehicle and using one of the example assets provided as a template (or have a mass that is similar to official content), you will likely want to use a value of ``2`` for this property. ---- .. _doc_assets_vehicle:explosion_max_force: Explosion_Max_Force :ref:`vector3 ` ``(0, 1024, 0)`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum amount of force applied on the 𝘟\-, 𝘠\-, and 𝘡-axis, when the vehicle explodes. ---- .. _doc_assets_vehicle:explosion_min_force: Explosion_Min_Force :ref:`vector3 ` ``(0, 1024, 0)`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum amount of force applied on the 𝘟\-, 𝘠\-, and 𝘡-axis, when the vehicle explodes. ---- .. _doc_assets_vehicle:explosions_invulnerable: Explosions_Invulnerable :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::::::::::: The vehicle cannot be damaged by explosions. ---- .. _doc_assets_vehicle:forwardgearratios: ForwardGearRatios :ref:`list of float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Ratio between engine RPM and wheel RPM in a given gear. For example, if the wheel RPM is 6 and the gear ratio is 5 then the engine RPM is 30. .. note:: When converting vanilla cars to gear ratios, the approach I used was to calculate the gear ratio for a desired speed and engine RPM. Suppose you're targeting 80 kph with a wheel radius of 0.6 m: 1. Convert 80 kph to m/s, in this case, 22.2 m/s. 2. Calculate wheel circumference with 2 * pi * r, in this case 3.77 m. 3. Calculate how far the vehicle would travel in a minute. 22.2 m/s * 60 s/min is 1,333.2 m/min. 4. Divide the distance per minute by the circumference to get the wheel RPM of 353.6776. Supposedly (I'm still learning as I go) engines work most efficiently around the upper-middle of their RPM range. For example, 3500 RPM for an engine with 1000 idle RPM and 6000 max RPM. Using 3500 as our target engine RPM we can divide it by the wheel RPM to get a good starting point for the gear ratio tuning: 9.89. ---- .. _doc_assets_vehicle:fuel: Fuel :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::: Total fuel capacity. ---- .. _doc_assets_vehicle:fuel_burn_rate: Fuel_Burn_Rate :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: This controls the rate at which fuel decreases per second. Defaults to ``2.05`` when using ``Engine Car``, or to ``4.2`` otherwise. ---- .. _doc_assets_vehicle:fuel_max: Fuel_Max :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum possible fuel to spawn with. ---- .. _doc_assets_vehicle:fuel_min: Fuel_Min :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum possible fuel to spawn with. ---- .. _doc_assets_vehicle:gearshift_allowskippinggears: GearShift_AllowSkippingGears :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, engine can skip from (for example) 1st to 3rd gear if it keeps RPM within the acceptable range. ---- .. _doc_assets_vehicle:gearshift_downthresholdrpm: GearShift_DownThresholdRPM :ref:`float32 ` ``1500.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When engine RPM is below this value and a lower gear is available the car will shift gears down. ---- .. _doc_assets_vehicle:gearshift_duration: GearShift_Duration :ref:`float32 ` ``0.5`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How long it takes to shift gears, measured in seconds. Wheels do not provide any torque for this duration. ---- .. _doc_assets_vehicle:gearshift_interval: GearShift_Interval :ref:`float32 ` ``1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How long to wait since the last gear change before shifting gears, measured in seconds. It can take a moment for the engine RPM to adjust after a gear change, so without a delay the RPM would still exceed the threshold. ---- .. _doc_assets_vehicle:gearshift_upthresholdrpm: GearShift_UpThresholdRPM :ref:`float32 ` ``5500.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When engine RPM is above this value and a higher gear is available the car will shift gears up. ---- .. _doc_assets_vehicle:gearshift_visibleinhud: GearShift_VisibleInHUD :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If gears are configured and this is true, RPM and gear number will be shown in the user interface. ---- .. _doc_assets_vehicle:guid: GUID :ref:`doc_data_guid` ::::::::::::::::::::::::: Refer to :ref:`GUID ` documentation. Vehicles are required to have this property. .. tip:: If the GUID property has been omitted from the asset file, then the game will automatically attempt to assign a random (and unique) GUID during a successful load. ---- .. _doc_assets_vehicle:has_clip_prefab: Has_Clip_Prefab :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Whether or not the vehicle has a Clip.prefab. If the vehicle should use the same prefab on the server as on the client, set to false. For example, most official content uses ``Has_Clip_Prefab false``. ---- .. _doc_assets_vehicle:has_horn: Has_Horn :ref:`bool ` ::::::::::::::::::::::::::::::::::::::::::::: Whether or not the vehicle should have a horn. Defaults to ``true`` when the vehicle either has a ``Horn`` AudioClip, or the ``HornAudioClip`` property has been set to a valid path. Otherwise, defaults to ``false``. ---- .. _doc_assets_vehicle:health: Health :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::: Total health value. ---- .. _doc_assets_vehicle:health_max: Health_Max :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum possible health to spawn with. ---- .. _doc_assets_vehicle:health_min: Health_Min :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum possible health to spawn with. ---- .. _doc_assets_vehicle:hornaudioclip: HornAudioClip :ref:`Master Bundle Pointer ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioClip to play when using the horn. ---- .. _doc_assets_vehicle:id: ID :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::: Must be a unique identifier. This property used to be required by vehicles, but this is no longer necessary. The range reserved for official content is [1, 2000). ---- .. _doc_assets_vehicle:ignitionaudioclip: IgnitionAudioClip :ref:`Master Bundle Pointer ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioClip to play after entering the driver's seat. ---- .. _doc_assets_vehicle:invulnerable: Invulnerable :ref:`flag ` :::::::::::::::::::::::::::::::::::::::: The vehicle cannot be damaged by lower-power :ref:`doc_item_asset_weapon` that do not have the ``Invulnerable`` flag. ---- .. _doc_assets_vehicle:ispaintable: IsPaintable :ref:`bool ` :::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, :ref:`Vehicle Paint Tools ` can be used on this vehicle. Defaults to ``true`` if :ref:`PaintableSections ` has been configured. ---- .. _doc_assets_vehicle:lift: Lift :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::: The amount of upwards lift force to apply, when using ``Engine Plane``. ---- .. _doc_assets_vehicle:lockmouse: LockMouse :ref:`flag ` ::::::::::::::::::::::::::::::::::::: First-person camera movement is locked while driving. This is useful for ``Engine Plane`` and ``Engine Helicopter``, as a player's mouse movement while in first-person can be used to steer the vehicle. ---- .. _doc_assets_vehicle:num_steering_tires: Num_Steering_Tires :ref:`int32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: .. deprecated:: 3.23.4.0 Replaced by the ``WheelConfigurations`` property. Total number of tires that should turn when steering. Defaults to ``2`` when using ``Engine Car``, to ``1`` when using any other ``Engine`` enumerator, or to ``0`` if the ``Crawler`` property has been set. ---- .. _doc_assets_vehicle:override_center_of_mass: Override_Center_Of_Mass :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, overrides the vehicle's center of mass with the values from the ``Center_Of_Mass`` property. This allows for modifying a vehicle's center of gravity without needing to move the "Cog" GameObject in Unity. ---- .. _doc_assets_vehicle:paintablesections: PaintableSections :ref:`list of PaintableVehicleSection ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If set, the vehicle can be painted with a :ref:`Vehicle Paint Tool `. Each section's material's ``_PaintColor`` property is set to the vehicle's paint color. ---- .. _doc_assets_vehicle:passenger_explosion_armor: Passenger_Explosion_Armor :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the damage taken by players sitting in the vehicle, by explosions. ---- .. _doc_assets_vehicle:physics_profile: Physics_Profile :ref:`GUID ` ::::::::::::::::::::::::::::::::::::::::::: GUID of a :ref:`VehiclePhysicsProfileAsset ` to use. Physics profiles allow for increased control over vehicle settings in bulk, but are not required for anything. There are several default profiles. These are used when the vehicle's :ref:`Engine ` property has been set to ``Boat``, ``Car``, ``Helicopter``, or ``Plane``, when certain conditions are met. The Vehicle.prefab's root RigidBody component must have a mass equal to 1.0, and any of its Tires' WheelColliders must also have a mass equal to 1.0. Otherwise, nothing is used by default. - ``Boat`` defaults to ``47258d0dcad14cb8be26e24c1ef3449e``. - ``Car`` defaults to ``6b91a94f01b6472eaca31d9420ec2367``. - ``Helicopter`` defaults to ``bb9f9f0204c4462ca7d976b87d1336d4``. - ``Plane`` defaults to ``93a47d6d40454335b4784e803628ac54``. Other vehicle types do not have a default profile. ---- .. _doc_assets_vehicle:pitch_drive: Pitch_Drive :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the pitch of the engine audio while driving. Defaults to ``0.03`` when using ``Engine Helicopter``, or to ``0.1`` when using ``Engine Blimp``. For other ``Engine`` enumerators, it defaults to ``0.025`` if the audio clip is named "Engine_Large", or to ``0.075`` if the audio clip is named "Engine_Small". Otherwise, defaults to ``0.05``. ---- .. _doc_assets_vehicle:pitch_idle: Pitch_Idle :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the pitch of the engine audio while idle. Defaults to ``0.625`` if the audio clip is named "Engine_Large", or to ``0.75`` if the audio clip is named "Engine_Small". Otherwise, defaults to ``0.5``. ---- .. _doc_assets_vehicle:rarity: Rarity :ref:`doc_data_eitemrarity` ``Common`` ::::::::::::::::::::::::::::::::::::::::::::: Rarity of the item, as text shown in menus and colors used for highlights. ---- .. _doc_assets_vehicle:reclined: Reclined :ref:`flag ` :::::::::::::::::::::::::::::::::::: Player character should use a reclined idle animation. ---- .. _doc_assets_vehicle:reversegearratio: ReverseGearRatio :ref:`float32 ` ``1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Gear ratio to use when reversing. Please refer to :ref:`ForwardGearRatios ` for more details on gear ratios. ---- .. _doc_assets_vehicle:rollangularvelocitydamping: RollAngularVelocityDamping :ref:`float32 ` ``-1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If greater than zero, an acceleration is applied to angular velocity on 𝘡-axis toward zero. ---- .. _doc_assets_vehicle:shared_skin_lookup_id: Shared_Skin_Lookup_ID :ref:`doc_data_guid` or :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of another vehicle, which this vehicle should share skins with. This property was used by some official vehicles (such as the `Rally Car `_), as each paint color used to be a separate vehicle. This is no longer necessary, but some modded vehicles may still rely on this functionality. Defaults to the value of this vehicle's configured ``GUID``. ---- .. _doc_assets_vehicle:shared_skin_name: Shared_Skin_Name :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: When generating images, the image name will contain the value of this string instead of the vehicle's file name. Often used with ``Shared_Skin_Lookup_ID``. ---- .. _doc_assets_vehicle:should_spawn_seat_capsules: Should_Spawn_Seat_Capsules :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, capsule colliders will be attached to the ``Seat`` GameObject in order to prevent players from clipping into the ground. This is useful for vehicles that do not have a roof, such as bicycles. ---- .. _doc_assets_vehicle:shouldexplosionburnmaterials: ShouldExplosionBurnMaterials :ref:`bool ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, the materials of the vehicle's ``Model_#`` GameObjects will be tinted black when the vehicle is destroyed. Defaults to ``true`` if the ``Explosion`` property is configured. ---- .. _doc_assets_vehicle:explosionburnmaterialsections: ExplosionBurnMaterialSections :ref:`list of PaintableVehicleSection ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Only used if ``ShouldExplosionBurnMaterials`` is ``true``. If set, manually specifies which materials should be darkened after an explosion. ---- .. _doc_assets_vehicle:shouldexplosioncausedamage: ShouldExplosionCauseDamage :ref:`bool ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, the explosion caused by the vehicle being destroyed will deal damage to nearby entities, and kill any passengers. Defaults to ``true`` if the ``Explosion`` property is configured. ---- .. _doc_assets_vehicle:size2_z: Size2_Z :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Orthogonal camera size for economy icons. ---- .. _doc_assets_vehicle:sleds: Sleds :ref:`flag ` ::::::::::::::::::::::::::::::::: Tires should easily roll. For example, most planes will want to use this property. ---- .. _doc_assets_vehicle:speed_max: Speed_Max :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: The vehicle's maximum velocity to aim for while accelerating forward, in m/s (meters per second). For all ``Engine`` enumerators except for the ``Train`` enumerator, this value is multiplied by 1.25 because the vehicle adjusts wheel torque trying to match a specific speed. For example, a vehicle that uses ``Speed_Max 12.5`` and is using ``Engine Car`` will have a maximum forward speed of 56.25 kph (34.95 mph). ---- .. _doc_assets_vehicle:speed_min: Speed_Min :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: The vehicle's maximum velocity to aim for while accelerating in reverse, in m/s (meters per second). In-game, a vehicle's speed is displayed as either kph (kilometers per hour) or mph (miles per hour). For example, a vehicle that uses ``Speed_Min -7`` will have a maximum reversing speed of 25.2 kph (15.66 mph). ---- .. _doc_assets_vehicle:stamina_boost: Stamina_Boost :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: When a value is specified, this property allows for using stamina to boost. The value specified is the multiplier on the speed a vehicle can go without using a stamina boost. For example, ``Stamina_Boost 0.5`` would only let vehicle move at 50% its maximum speed normally, but using stamina to boost would it reach its maximum speed. This property is often used with ``Stamina_Powered``, but this is not required. ---- .. _doc_assets_vehicle:stamina_powered: Stamina_Powered :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::: The vehicle does not use fuel or a vehicle battery. ---- .. _doc_assets_vehicle:steering_angle_fullspeed_factor: Steering_Angle_FullSpeed_Factor :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier for steering angle range at target maximum speed (for the current forward/backward direction). Reducing steering range at higher speeds keeps the vehicle controlable with digital (non-analog) input. ---- .. _doc_assets_vehicle:steering_angle_max: Steering_Angle_Max :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Steering angle range at zero speed (idle/parked). For example, 45 means the wheels connected to steering can rotate ±45 degrees. ---- .. _doc_assets_vehicle:steer_max: Steer_Max :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: .. tip:: This property was replaced by :ref:`Steering_Angle_Max ` which **isn't** multiplied by 0.75. Steering angle range at zero speed (idle/parked). This value is multiplied by 0.75. ---- .. _doc_assets_vehicle:steer_min: Steer_Min :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: .. tip:: This property was replaced by :ref:`Steering_Angle_FullSpeed_Factor `. Steering angle range at target maximum speed (for the current forward/backward direction). ---- .. _doc_assets_vehicle:steering_angle_turn_speed: Steering_Angle_Turn_Speed :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How quickly wheels can turn to meet player input, measured in degrees per second. Defaults to the value of ``Steer_Max * 5.0``. ---- .. _doc_assets_vehicle:steering_leaningforcemultiplier: Steering_LeaningForceMultiplier :ref:`float32 ` ``-1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If greater than zero, torque is applied on 𝘡-axis according to steering input for bikes and motorcycles. ---- .. _doc_assets_vehicle:steering_leaningforce_scalewithspeed: Steering_LeaningForce_ScaleWithSpeed :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, leaning force is multiplied by normalized speed to the power of Steering_LeaningForce_SpeedExponent. Defaults to false. ---- .. _doc_assets_vehicle:steering_leaningforce_speedexponent: Steering_LeaningForce_SpeedExponent :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Refer to Steering_LeaningForce_ScaleWithSpeed. ---- .. _doc_assets_vehicle:steering_tire_#: Steering_Tire_# :ref:`int32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: .. deprecated:: 3.23.4.0 Replaced by the ``WheelConfigurations`` property. Set a ``Wheel_#`` GameObject as a steering tire, which will visibly turn when steering. By default, a number of steering tires equal to the value of ``Num_Steering_Tires`` will be automatically set. These will start at ``Steering_Tire_0 0`` (corresponding to ``Wheel_0``), and increment upwards. ---- .. _doc_assets_vehicle:tire_id: Tire_ID :ref:`uint16 ` ``1451`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: ID of the item that should be given when a tire is manually removed with a :ref:`ToolAsset ` that has ``Mode Remove``, and can also be manually attached to the vehicle if the specified item ID is for a :ref:`ToolAsset ` with ``Mode Add``. ---- .. _doc_assets_vehicle:tires_invulnerable: Tires_Invulnerable :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::: Tires cannot be damaged. ---- .. _doc_assets_vehicle:traction: Traction :ref:`flag ` :::::::::::::::::::::::::::::::::::: Tires should have traction in snowy positions. ---- .. _doc_assets_vehicle:train_car_length: Train_Car_Length :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The distance between each train car on the train, in meters. This property is used with ``Engine Train``. ---- .. _doc_assets_vehicle:train_track_offset: Train_Track_Offset :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The offset the train car is above the track, in meters. This property is used with ``Engine Train``. ---- .. _doc_assets_vehicle:train_wheel_offset: Train_Wheel_Offset :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The offset between the wheels, in meters. This property is used with ``Engine Train``. ---- .. _doc_assets_vehicle:trunk_storage_x: Trunk_Storage_X :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Number of columns (horizontal storage space). ---- .. _doc_assets_vehicle:trunk_storage_y: Trunk_Storage_Y :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Number of rows (vertical storage space). ---- .. _doc_assets_vehicle:turret_ignore_aim_camera: Turret_#_Ignore_Aim_Camera :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Normally, the player's camera is positioned at the "Aim" GameObject. Including this flag will disable this feature. ---- .. _doc_assets_vehicle:turret_item_id: Turret_#_Item_ID :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of the item usable from the turret seat. This is often used with a :ref:`GunAsset ` that has the ``Turret`` property. However, other items can be used – although most will function in unintended ways. ---- .. _doc_assets_vehicle:turret_pitch_max: Turret_#_Pitch_Max :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum allowed rotation of the turret through the elevation, in degrees. ---- .. _doc_assets_vehicle:turret_pitch_min: Turret_#_Pitch_Min :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum allowed rotation of the turret through the elevation, in degrees. ---- .. _doc_assets_vehicle:turret_seat_index: Turret_#_Seat_Index :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Index of the "Seat_#" GameObject that this turret is usable from. For example, ``0`` would correspond to "Seat_0". ---- .. _doc_assets_vehicle:turret_yaw_max: Turret_#_Yaw_Max :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum allowed rotation of the turret through the azimuth, in degrees. If this is set to ``360``, it can rotate rightward forever. ---- .. _doc_assets_vehicle:turret_yaw_min: Turret_#_Yaw_Min :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum allowed rotation of the turret through the azimuth, in degrees. If this is set to ``-360``, it can rotate leftward forever. ---- .. _doc_assets_vehicle:turrets: Turrets :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::: Total number of turrets on the vehicle. All other turret-related properties require that this property has been configured. For example, this is how the `Fighter Jet `_ is configured: .. code-block:: unturneddat :linenos: Turrets 1 Turret_0_Seat_Index 0 Turret_0_Item_ID 1471 Turret_0_Yaw_Min -135 Turret_0_Yaw_Max 135 Turret_0_Pitch_Min 85 Turret_0_Pitch_Max 180 Turret_0_Ignore_Aim_Camera ---- .. _doc_assets_vehicle:type: Type :ref:`doc_data_eassettype` ::::::::::::::::::::::::::::::: Designates the vehicle's class. Vehicle assets are required to have this property. ---- .. _doc_assets_vehicle:valid_speed_down: Valid_Speed_Down :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Configuring this will override the downward vertical speed sanity check on the Y-axis, measured in m/s (meters per second). Multiplayer checks if speed exceeds this value, and the movement is marked as invalid if so. Defaults to ``25`` when using ``Engine Car`` or ``Engine Boat``, or to ``100`` otherwise. ---- .. _doc_assets_vehicle:valid_speed_horizontal: Valid_Speed_Horizontal :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Configuring this will override the horizontal speed sanity check on the XZ plane, measured in m/s (meters per second). Multiplayer checks if speed exceeds this value, and the movement is marked as invalid if so. Defaults to ``(Speed_Max * 0.125)^2`` when using ``Engine Helicopter`` or ``Engine Blimp``, or to ``(Speed_Max * 0.1)^2`` otherwise. This property is useful for vehicles with speed that the server cannot predict, such as force-applying Unity components. ---- .. _doc_assets_vehicle:valid_speed_up: Valid_Speed_Up :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Configuring this will override the upward vertical speed sanity check on the Y-axis, measured in m/s (meters per second). Multiplayer checks if speed exceeds this value, and the movement is marked as invalid if so. Defaults to 12.5 when using ``Engine Car``, to 3.25 when using ``Engine Boat``, or to 100 otherwise. ---- .. _doc_assets_vehicle:wheel_collider_mass_override: Wheel_Collider_Mass_Override :ref:`float32 ` ``null`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Override the mass of the vehicle's WheelCollider components. This allows for quickly modifying the mass of the wheel colliders without needing to rebundle the asset in Unity. If a vehicle has realistic mass, then it may be helpful to set this value to something exceptionally high (e.g., ``500``). ---- .. _doc_assets_vehicle:wheelbalancing_forcemultiplier: WheelBalancing_ForceMultiplier :ref:`float32 ` ``-1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If greater than zero, torque is applied on the Z axis multiplied by this factor to align vehicle up with ground up. .. note:: :ref:`RollAngularVelocityDamping ` is critical for damping this force. ---- .. _doc_assets_vehicle:wheelbalancing_uprightexponent: WheelBalancing_UprightExponent :ref:`float32 ` ``1.5`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Exponent on the 0 to 1 factor representing how aligned the vehicle is with the ground up vector. For example, a value of 2 would apply much less force while nearly aligned with up, whereas a value of 0.5 would apply more force even while nearly aligned with up. ---- .. _doc_assets_vehicle:wheelconfigurations: WheelConfigurations :ref:`list of VehicleWheelConfiguration ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls WheelCollider components and their corresponding visual models. When converting older vehicles, enable the ``-LogVehicleWheelConfigurations`` command-line flag to output an equivalent wheel configuration. For example, this is how the `Ambulance `_ is configured: .. code-block:: unturneddat :linenos: WheelConfigurations [ { WheelColliderPath Tires/Tire_0 IsColliderSteered true IsColliderPowered true ModelPath Wheels/Wheel_0 ModelUseColliderPose true } { WheelColliderPath Tires/Tire_1 IsColliderSteered true IsColliderPowered true ModelPath Wheels/Wheel_1 ModelUseColliderPose true } { WheelColliderPath Tires/Tire_2 IsColliderSteered false IsColliderPowered false ModelPath Wheels/Wheel_2 ModelUseColliderPose true } { WheelColliderPath Tires/Tire_3 IsColliderSteered false IsColliderPowered false ModelPath Wheels/Wheel_3 ModelUseColliderPose true } ] ---- .. _doc_assets_vehicle:zip: Zip :ref:`flag ` ::::::::::::::::::::::::::::::: Player character should use a handlebar idle animation. ---- CrawlerTrackTilingMaterial Dictionary Descriptions ``````````````````````````````````````````````````` .. _doc_assets_vehicle:crawlertracktilingmaterial_path: Path :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::: Scene hierarchy path to a Renderer component relative to the vehicle's root transform. ---- .. _doc_assets_vehicle:crawlertracktilingmaterial_materialindex: MaterialIndex :ref:`int32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::: Index into Renderer component's Materials list. For example, ``0`` is the 1st material, ``1`` is the 2nd material, and so forth. ---- .. _doc_assets_vehicle:crawlertracktilingmaterial_wheelindices: WheelIndices :ref:`list of int32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Index into wheel configurations list. For example, ``0`` is the 1st wheel, ``1`` is the 2nd wheel, and so forth. The average of these wheels' RPM is used to calculate how fast crawler track is moving. ---- .. _doc_assets_vehicle:crawlertracktilingmaterial_repeatdistance: RepeatDistance :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: How far to travel to offset UV 1x. You can calculate RepeatDistance by selecting an edge parallel to the crawler track and dividing the UV distance by the physical 3D distance. For example, if the UV length is 2 and the 3D length is 1.5 m then the texture repeats 1.33 UV/m. ---- .. _doc_assets_vehicle:crawlertracktilingmaterial_uv_direction: UV_Direction :ref:`Vector2 ` :::::::::::::::::::::::::::::::::::::::::::::::::::: For example, ``(-1.0, 0.0)`` will move the UV offset left as the vehicle travels forward. ---- PaintableVehicleSection Dictionary Descriptions ``````````````````````````````````````````````` .. _doc_assets_vehicle:paintablevehiclesection_path: Path :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::: Scene hierarchy path to a Renderer component relative to the vehicle's root transform. ---- .. _doc_assets_vehicle:paintablevehiclesection_materialindex: MaterialIndex :ref:`int32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Index into Renderer component's Materials list. For example, ``0`` is the 1st material, ``1`` is the 2nd material, and so forth. ---- .. _doc_assets_vehicle:paintablevehiclesection_allmaterials: AllMaterials :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, apply to all materials in Renderer component's Materials list, rather than a specific index. RpmEngineSoundConfiguration Dictionary Descriptions ``````````````````````````````````````````````````` .. _doc_assets_vehicle:rpmenginesoundconfiguration_idlepitch: IdlePitch :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioSource pitch when engine RPM is at :ref:`Idle RPM `. ---- .. _doc_assets_vehicle:rpmenginesoundconfiguration_idlevolume: IdleVolume :ref:`float32 ` ``0.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioSource volume when engine RPM is at :ref:`Idle RPM `. ---- .. _doc_assets_vehicle:rpmenginesoundconfiguration_maxpitch: MaxPitch :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioSource pitch when engine RPM is at :ref:`Max RPM `. ---- .. _doc_assets_vehicle:rpmenginesoundconfiguration_maxvolume: MaxVolume :ref:`float32 ` ``0.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioSource volume when engine RPM is at :ref:`Max RPM `. VehicleRandomPaintColorConfiguration Dictionary Descriptions ```````````````````````````````````````````````````````````` .. _doc_assets_vehicle:vehiclerandompaintcolorconfiguration_minsaturation: MinSaturation :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum random saturation in HSV color to generate. ---- .. _doc_assets_vehicle:vehiclerandompaintcolorconfiguration_maxsaturation: MaxSaturation :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum random saturation in HSV color to generate. ---- .. _doc_assets_vehicle:vehiclerandompaintcolorconfiguration_minvalue: MinValue :ref:`float32 ` ``0.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum value or brightness in HSV color to generate. ---- .. _doc_assets_vehicle:vehiclerandompaintcolorconfiguration_maxvalue: MaxValue :ref:`float32 ` ``0.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum value or brightness in HSV color to generate. ---- .. _doc_assets_vehicle:vehiclerandompaintcolorconfiguration_grayscalechance: GrayscaleChance :ref:`float32 ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: [0, 1] color will have zero saturation if random value is less than this. For example, 0.2 means 20% of vehicles will be grayscale. VehicleWheelConfiguration Dictionary Descriptions ````````````````````````````````````````````````` .. _doc_assets_vehicle:wheelconfiguration_canexplode: CanExplode :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, wheel should fly off when vehicle explodes. Defaults to true. Used to simplify destroying vehicles with crawler tracks. ---- .. _doc_assets_vehicle:wheelconfiguration_copycolliderrpmindex: CopyColliderRpmIndex :ref:`int32 ` ``-1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If set, visual-only wheels without a collider (like the back wheels of the snowmobile) can copy RPM from a wheel that does have a collider. Requires :ref:`ModelRadius ` to also be set. ---- .. _doc_assets_vehicle:wheelconfiguration_crawlertrackforwardmode: CrawlerTrackForwardMode :ref:`ECrawlerTrackForwardMode ` ``Auto`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: For ``CrawlerTrack`` ``SteeringMode``, indicates how a positive motor torque (forward) rotates the vehicle. ---- .. _doc_assets_vehicle:wheelconfiguration_iscolliderpowered: IsColliderPowered :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, collider is connected to the engine and responds to player's acceleration input. ---- .. _doc_assets_vehicle:wheelconfiguration_iscollidersteered: IsColliderSteered :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, collider's steering angle responds to player input. .. deprecated:: 3.23.7.0 Replaced by the ``SteeringMode`` property. ---- .. _doc_assets_vehicle:wheelconfiguration_ismodelsteered: IsModelSteered :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, model is rotated according to steering input. Only kept for backwards compatibility. Prior to wheel configurations, only certain WheelColliders actually received steering input, while multiple models would appear to steer. For example, the APC's front 4 wheels appeared to rotate but only the front 2 actually affected physics. ---- .. _doc_assets_vehicle:wheelconfiguration_modelpath: ModelPath :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::::: Scene hierarchy path of visual representation of wheel relative to the vehicle's root transform. ---- .. _doc_assets_vehicle:wheelconfiguration_modelradius: ModelRadius :ref:`float32 ` ``-1.0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If greater than zero, visual-only wheels (without a collider) like the extra wheels of the Snowmobile use this radius to calculate their rolling speed. ---- .. _doc_assets_vehicle:wheelconfiguration_modelusecolliderpose: ModelUseColliderPose :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, model ignores ``IsModelSteered`` and instead uses the wheel collider state (or an approximation when not simulating). Prior to wheel configurations, some high-fidely modded cars used a separate set of physics constraints to animate the wheel models as if they had suspension. Constraint setups like this should be completely superseded by the ``ModelUseColliderPose`` property. The constraints were awful for performance because physics for every purely-visual wheel were simulated on every client, and even then they didn't actually match the real wheel state. ---- .. _doc_assets_vehicle:wheelconfiguration_modelsuspensionoffset: ModelSuspensionOffset :ref:`float ` ``0.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Vertical offset of model from simulated suspension position. Used by crawler tracks because the visual wheel rests on the tread above the physics wheel. ---- .. _doc_assets_vehicle:wheelconfiguration_modelsuspensionspeed: ModelSuspensionSpeed :ref:`float ` ``-1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How quickly to interpolate model toward suspension position in meters per second. If negative, position teleports immediately. ---- .. _doc_assets_vehicle:wheelconfiguration_motioneffects: MotionEffects :ref:`EWheelMotionEffectsMode ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls whether wheel creates particle kickup effects for the ground surface material underneath. Defaults to ``BothDirections`` if ``ModelUseColliderPose`` is true, ``None`` otherwise. ---- .. _doc_assets_vehicle:wheelconfiguration_steeringanglemultiplier: SteeringAngleMultiplier :ref:`float ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Target steering angle is multiplied by this value. For example, can be set to a negative number for rear-wheel steering. ---- .. _doc_assets_vehicle:wheelconfiguration_steeringmode: SteeringMode :ref:`EWheelSteeringMode ` ``Auto`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls whether wheel contributes to steering and if so, which kind of steering to simulate. ---- .. _doc_assets_vehicle:wheelconfiguration_wheelcolliderpath: WheelColliderPath :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Scene hierarchy path of a WheelCollider component relative to the vehicle's root transform. Localization ------------ **Name** *string*: Vehicle name in user interfaces. ================================================ FILE: assets/vehicle-physics-profile-asset.rst ================================================ .. _doc_assets_vehicle_physics_profile: Vehicle Physics Profile Assets ============================== This asset exists to tune vehicle physics in bulk without rebuilding asset bundles, and exposes more control than the individual vehicle assets. One of the goals introducing profiles is to improve the handling of vanilla wheeled vehicles. Feel free to experiment with the default profile, and propose changes to it. How to test? ------------ In 3.19.18.0 the **reload** command was introduced which can be used to reload specific assets or directories of assets while playing. Simply reload the physics profile and then respawn a vehicle. For example to reload the default profile: .. code-block:: shell /reload 6b91a94f01b6472eaca31d9420ec2367 How are vehicles assigned a profile? ------------------------------------ Individual vehicle assets can specify a profile by setting **Physics_Profile** to the GUID. If a profile is not set, and the vehicle prefab's root rigidbody has a mass of 1.0, and the wheel colliders also have masses of 1.0, the default profile at Bundles/Assets/VehiclePhysicsProfiles/DefaultProfile.asset is used. Asset Properties Reference -------------------------- **Type** *string*: ``SDG.Unturned.VehiclePhysicsProfileAsset`` **Root_Mass**: If set, overrides vehicle rigidbody's mass. **Root_Mass_Multiplier**: If set, multiplies vehicle rigidbody's mass. **Root_Drag_Multiplier**: If set, multiplies vehicle rigidbody's positional drag force. **Root_Angular_Drag_Multiplier**: If set, multiplies vehicle rigidbody's angular drag force. **Carjack_Force_Multiplier**: If set, multiplies carjack item's force applied. **Wheel_Mass**: If set, overrides wheel collider mass. Ignored if vehicle asset has Wheel_Collider_Mass_Override set. **Wheel_Mass_Multiplier**: If set, multiplies wheel collider mass. **Wheel_Damping_Rate**: If set, override wheel collider damping rate. Lower values accelerate faster. **Wheel_Suspension_Force**: If set, overrides wheel collider suspension force. **Wheel_Suspension_Damper**: If set, overrides wheel collider suspension damper. **Wheel_Stiffness_Traction_Multiplier**: Wheel collider stiffness multiplier when driving in snow. Default: 0.25 **Wheel_Friction_Sideways** and **Wheel_Friction_Forward**: * **Extremum_Slip**: If set, overrides friction curve extremum slip. * **Extremum_Value**: If set, overrides friction curve extremum value. * **Asymptote_Slip**: If set, overrides friction curve asymptote slip. * **Asymptote_Value**: If set, overrides friction curve asymptote value. * **Stiffness**: If set, overrides friction curve stiffness. Multiplies the extremum and asymptote values. Sideways default is 1.0 and forward default is 2.0. **Motor_Torque_Multiplier**: Multiplies wheel collider motor torque which is usually driven by vehicle speed. **Motor_Torque_Clamp_Multiplier**: Multiplies wheel collider motor torque when exceeding maximum speed. Default: 0.5 **Brake_Torque_Multiplier**: Multiplies wheel collider brake torque. **Brake_Torque_Traction_Multiplier**: Multiplies wheel collider brake torque when driving in snow. Default: 0.5 **Wheel_Drive_Model**: ``Front``, ``Rear`` or ``All``. By default all cars are rear-wheel drive, but in the real world cars are front-wheel drive. This discrepancy is due to a poor understanding of cars when they were added to the game in 2014. **Wheel_Brake_Model**: ``Front``, ``Rear`` or ``All``. Modern cars have all-wheel breaking, which is the default. ================================================ FILE: assets/vehicle-redirector-asset.rst ================================================ .. _doc_asset_vehicle_redirector: Vehicle Redirector Assets ========================= **Vehicle Redirector Assets** help consolidate legacy colored vehicle variants into a single vehicle asset. Prior to the addition of paintable vehicles, it was common to create duplicates of a vehicle asset with the color being the only difference. One of many downsides with this approach was the increased hassle of keeping changes consistent between all of the variants; for example, when tuning physics. Vehicle redirector assets ensure compatibility with existing saves and content while merging colored vehicle variants into one unified asset. Game Data File -------------- Note that the ``TargetVehicle`` property is required for this asset to function. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`TargetVehicle ` - :ref:`Asset Pointer ` - * - :ref:`LoadPaintColor ` - :ref:`color ` - * - :ref:`SpawnPaintColor ` - :ref:`color ` - Property Descriptions ````````````````````` .. _doc_asset_vehicle_redirector:targetvehicle: TargetVehicle :ref:`Asset Pointer ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Actual vehicle to use when attempting to load or spawn this asset. ---- .. _doc_asset_vehicle_redirector:loadpaintcolor: LoadPaintColor :ref:`color ` :::::::::::::::::::::::::::::::::::::::::::: If set, overrides the default random paint color when loading a vehicle from a save file. Used to preserve colors of vehicles in existing saves. ---- .. _doc_asset_vehicle_redirector:spawnpaintcolor: SpawnPaintColor :ref:`color ` ::::::::::::::::::::::::::::::::::::::::::::: If set, overrides the default random paint color when spawning a new vehicle. Optionally used to preserve colors of vehicles in spawn tables. ================================================ FILE: assets/weather-asset.rst ================================================ .. _doc_assets_weather: Weather Assets ============== Overrides the built-in snow and rain weather with custom events. This is feature is a work-in-progress. Random weather can be scheduled to occur naturally on a map with the ``Weather_Types`` property of the :ref:`Level Asset `. How to test? ------------ When a GUID is passed to the weather command it will start a custom weather event, and 0 can be used to end it. .. code-block:: shell /weather 819982d7a2b6453488a8c4c5d9efe67f Properties Reference -------------------- **Type** *string*: ``SDG.Unturned.WeatherAsset`` **Volume_Mask** :ref:`u32 Mask `: Only enabled while inside an ambience volume with non-zero bitwise AND result. Defaults to 0xFFFFFFFF. **Fade_In_Duration** *float*: Seconds between weather event starting and reaching full intensity. **Fade_Out_Duration** *float*: Seconds between weather event ending and reaching zero intensity. **Ambient_Audio_Clip** :ref:`Master Bundle Pointer `: Audio clip to play globally. Volume matches intensity. **Ambient_Audio_Takes_Priority_Over_Ambiance_Volumes** *bool*: If true, ``Ambient_Audio_Clip`` causes per-ambiance-volume audio to fade out. Defaults to false. **Override_Fog** *bool*: Should fog configured in the lighting be overridden? **Override_Atmospheric_Fog** *bool*: Should fog affect the skybox? **Shadow_Strength_Multiplier** *float*: Directional light shadow strength multiplier. **Fog_Blend_Exponent** *float*: Power applied to fog blending alpha. **Cloud_Blend_Exponent** *float*: Power applied to cloud blending alpha. **Wind_Main** *float*: Wind zone windMain value. Will be replaced by more configurable game-specific wind eventually. **Dawn**, **Midday**, **Dusk** and **Midnight**: Refer to the ":ref:`Time of Day `" section. **Effects** *array*: Refer to the ":ref:`Effects `" section. **Stamina_Per_Second** *float*: Stamina +/- buff. **Health_Per_Second** *float*: Health +/- buff. **Food_Per_Second** *float*: Food +/- buff. **Water_Per_Second** *float*: Water +/- buff. **Virus_Per_Second** *float*: Virus +/- buff. **Has_Lightning** *bool*: If true, lightning will be enabled for this weather type. In the future this should get cleaned up, but for now it is hardcoded for assigning a net id. **Min_Lightning_Interval** *float*: Minimum seconds between lightning strikes. **Max_Lightning_Interval** *float*: Maximum seconds between lightning strikes. **Fish_Bite_Interval_Multiplier** *float*: Multiplier for interval before a fish takes the bait. Defaults to 1. .. _doc_assets_weather:time_of_day: Time of Day Properties ---------------------- Each of the four main times of day can override certain properties. **Fog_Color** *struct*: Distance-based fog. Optionally overrides the skybox color. Refer to the ":ref:`Color `" section. **Fog_Density** *float*: Functions similarly to fog intensity in ambiance volume. Value must be within [0, 1]. **Cloud_Color** *struct*: Inner body of cloud. Refer to the ":ref:`Color `" section. **Cloud_Rim_Color** *struct*: Outer edge of cloud. More visible than inner color. Refer to the ":ref:`Color `" section. **Brightness_Multiplier** *float*: All ambient lighting colors are multiplied by this. .. _doc_assets_weather:effects: Effect Properties ----------------- Multiple effects can be instantiated while the weather is active. **Prefab** :ref:`Master Bundle Pointer `: Game object with a particle system. PlayOnAwake should be disabled. For effects tied to the view it may be helpful to change the culling mode to "Always Simulate". **Emission_Exponent** *float*: Power applied to weather intensity multiplied by default constant rate over time. **Pitch** *float*: X-axis rotation when ``Rotate_Yaw_With_Wind`` is enabled. **Translate_With_View** *bool*: Should position in world-space match the camera? The built-in snow and rain move with the view. Position is zeroed when false. May be useful for transition effects like dust blowing into the map signaling the start of a sandstorm. **Rotate_Yaw_With_Wind** *bool*: Should y-axis rotation match the wind direction? The built-in snow and rain rotate with wind. .. _doc_assets_weather:color: Color Properties ---------------- Each color can use a custom override, or a color from the level editor lighting panel. Using a level color is primarily for rain and snow backwards compatibility. **Level_Enum** *enum*: If set, then the RGB specified are multiplied by this color. **R**, **G**, **B** *uint8*: Color channel values. NPC Conditions -------------- Global weather state and current weather intensity blend can be tested through NPC conditions. Refer to :ref:`Conditions ` documentation for documentation. ================================================ FILE: assets/zombie-difficulty-asset.rst ================================================ .. _doc_assets_zombie_difficulty: Zombie Difficulty Assets ======================== Override the difficulty settings for zombies in a navmesh. For reference, official ZombieDifficulty.asset files can be found at ``...\Steam\steamapps\common\Unturned\Bundles\Assets\Zombie_Difficulty``. Properties Reference -------------------- **Type** *string*: ``SDG.Unturned.ZombieDifficultyAsset`` **Overrides_Spawn_Chance** *bool*: Whether or not the spawn chance for zombies in the navmesh should be overridden by the values set in this asset. For example, it may be useful to set this to ``false`` if you *only* wanted to tweak properties not related to spawn chances, such as the damage thresholds for stuns. Defaults to true. **Mega_Stun_Threshold** *int*: Override the damage threshold for a hit to cause a stun. **Normal_Stun_Threshold** *int*: Override the damage threshold for a hit to cause a stun. **Allow_Horde_Beacon** *bool*: Whether or not Horde Beacons can be placed in the navmesh. Defaults to true. **Speciality_Health_Override_Mode** ``None``, ``MultiplyEditorHealth``, ``MultiplyDefaultHealth``, or ``Replace``: defaults to ``None``. If set, allows zombie health to overridden per-zombie-type. - ``None``: Do not override zombie health. - ``MultiplyEditorHealth``: Per-speciality value is a multiplier for health configured in the level editor. - ``MultiplyDefaultHealth``: Per-speciality value is a multiplier for vanilla health value. - ``Replace``: Per-speciality value replaces zombie's health. **Speciality_Health_Overrides** *dictionary*: If using ``Speciality_Health_Override_Mode``, this pairs zombie speciality (e.g., Crawler, Sprinter, Flanker, etc) to a number. For example: .. code-block:: unturnedasset :linenos: Speciality_Health_Overrides { Crawler 100 Burner 200 } Spawn Chance Properties ----------------------- **Crawler_Chance** *float*: Decimal-to-percent chance for the zombie to be a Crawler. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Sprinter_Chance** *float*: Decimal-to-percent chance for the zombie to be a Sprinter. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Flanker_Chance** *float*: Decimal-to-percent chance for the zombie to be a Flanker. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Burner_Chance** *float*: Decimal-to-percent chance for the zombie to be a Burner. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Acid_Chance** *float*: Decimal-to-percent chance for the zombie to be a Acid Spitter. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Boss_Electric_Chance** *float*: Decimal-to-percent chance for the zombie to be a Lightningstrike Zombie Boss. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Boss_Wind_Chance** *float*: Decimal-to-percent chance for the zombie to be a Groundpounder Zombie Boss. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Boss_Fire_Chance** *float*: Decimal-to-percent chance for the zombie to be a Flamethrower Zombie Boss. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Spirit_Chance** *float*: Decimal-to-percent chance for the zombie to be a Spirit. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **DL_Red_Volatile_Chance** *float*: Decimal-to-percent chance for the zombie to be a Volatile. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **DL_Blue_Volatile_Chance** *float*: Decimal-to-percent chance for the zombie to be a Blue Volatile. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Boss_Elver_Stomper_Chance** *float*: Decimal-to-percent chance for the zombie to be a Stomper Zombie Boss. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. **Boss_Kuwait_Chance** *float*: Decimal-to-percent chance for the zombie to be an Evil Eye Zombie Boss. Defaults to 0. Requires ``Overrides_Spawn_Chance`` to be true. ================================================ FILE: conf.py ================================================ # Configuration file for the Sphinx documentation builder. # # https://www.sphinx-doc.org/en/master/usage/configuration.html import sphinx import sphinx_rtd_theme # "Read the Docs Sphinx Theme" https://sphinx-rtd-theme.readthedocs.io/en/stable/index.html import sys import os # -- Project information project = "Unturned" copyright = "2023, Smartly Dressed Games" author = "Smartly Dressed Games" version = "3.x" release = version # -- General configuration sys.path.append(os.path.abspath("_extensions")) # also find extensions within this directory extensions = [ "notfound.extension", # Adds custom "404 Not Found" page 'sphinx.ext.duration', 'sphinx.ext.doctest', 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx_copybutton', 'sphinx.ext.intersphinx', 'sphinxext.opengraph', # OpenGraph support (e.g., URLs posted offsite appear as OneBox embeds) 'sphinx_tabs.tabs', # -- Locally-installed modules 'unturned_lexer', ] exclude_patterns = [ '.venv/*' # Contains installed packages which may have .rst files we don't want included in source files. ] intersphinx_mapping = { 'python': ('https://docs.python.org/3/', None), 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), } intersphinx_disabled_domains = ['std'] templates_path = ['_templates'] # -- Options for HTML output html_theme = "sphinx_rtd_theme" # RTD theme options are documented here: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html html_theme_options = { # Toc options 'collapse_navigation': True, } # Define the canonical URL if you are using a custom domain on Read the Docs html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "") # These folders are copied to the documentation's HTML output html_static_path = ["_static"] # These paths are either relative to html_static_path # or fully qualified paths (e.g. https://...) html_css_files = [ 'css/custom.css', 'css/toctree_collapse.css', ] html_js_files = [ "js/toctree_collapse.js", ] # -- Options for EPUB output epub_show_urls = 'footnote' ================================================ FILE: data/asset-ptr.rst ================================================ .. _doc_data_assetptr: Asset Pointer ============= When an asset refers to another it does so using an **Asset Pointer**. These identify the target asset by its :ref:`GUID `. In \*.dat files --------------- Note that the GUID here is not wrapped in quotes because Unturned \*.dat files are treated as pairs of strings. .. code-block:: unturneddat MyAssetPtr ################################ In \*.asset files ----------------- Two formats are supported in these files. The inline style was added later so you will see the older style used in many official assets. .. code-block:: unturnedasset "MyAssetPtr" "################################" "MyAssetPtr" { "GUID" "################################" } In JSON files ------------- .. code-block:: json "MyAssetPtr": { "GUID": "################################" } ================================================ FILE: data/bitmask.rst ================================================ .. _doc_data_bitmask: Bitmask ======= `Recommended Wikipedia Article `_ Weather Example --------------- Rain's default mask is 1 (0b01), and snow's default mask is 2 (0b10). An ambience volume could enable both with 3 (0b11), or neither with 0 (0b00). ================================================ FILE: data/built-in-types.rst ================================================ .. _doc_data_builtin_types: C# Built-in Types ================= The following table lists the **C# built-in types**, along with common aliases and default values: .. list-table:: :widths: 20 20 40 20 :header-rows: 1 * - C# type - Alias(es) - Range - Default Value * - bool - Boolean - ``true`` or ``false`` - ``false`` * - int8 - sbyte - ``-128`` to ``127`` - ``0`` * - uint8 - byte - ``0`` to ``255`` - ``0`` * - int16 - short - ``-32768`` to ``32767`` - ``0`` * - uint16 - ushort - ``0`` to ``65535`` - ``0`` * - float32 - float, single - precision up to seven digits - ``0`` * - int32 - int - ``-2147483648`` to ``2147483647`` - ``0`` * - uint32 - uint - ``0`` to ``4294967295`` - ``0`` * - float64 - double - precision up to fifteen digits - ``0`` * - int64 - long - ``-9223372036854775808`` to ``9223372036854775807`` - ``0`` * - uint64 - ulong - ``0`` to ``18446744073709551615`` - ``0`` * - string - - a sequence of zero or more Unicode characters - ``null`` For more information about any of these built-in types, it is recommended to view Microsoft's `"Built-in types (C# reference)" `_ documentation page. ================================================ FILE: data/color.rst ================================================ .. _doc_data_color: Color ===== **Colors** can either be parsed as a single hexadecimal value (optionally prefixed with ``#``), or from a dictionary with ``R``, ``G``, and ``B`` keys with :ref:`uint8 ` values. For example, all three of these would be valid colors: .. code-block:: text SkyColor 0000ff GroundColor #00ff00 FogColor { R 255 G 0 B 0 } Legacy Parsing -------------- Some older properties have support for the color data type, but can alternatively be written using the legacy method of three separate :ref:`float32 ` properties. Namely, the ``Laser_Color`` and ``Nightvision_Color`` properties have support for both. For example, this would be valid for an older property that supports the legacy format: .. code-block:: text Laser_Color_R 0.5 Laser_Color_G 1 Laser_Color_B 0 ================================================ FILE: data/enum/eassettype.rst ================================================ .. _doc_data_eassettype: EAssetType ========== The EAssetType enumerated type is used as a scope for legacy IDs. Each legacy ID is unique within an EAssetType (allowing multiple assets to share the same legacy ID when they are different types). This is only used in older code or for maintaining backwards compatibility. Enumerators ``````````` .. list-table:: :widths: 20 10 70 :header-rows: 1 * - Named Value - Index - Description * - ``None`` - 0 - Asset type is not applicable. * - ``Item`` - 1 - Asset is an item. * - ``Effect`` - 2 - Asset is an effect. * - ``Object`` - 3 - Asset is an object (this includes NPC characters). * - ``Resource`` - 4 - Asset is a resource. * - ``Vehicle`` - 5 - Asset is a vehicle. * - ``Animal`` - 6 - Asset is an animal. * - ``Mythic`` - 7 - Asset is a mythical effect. * - ``Skin`` - 8 - Asset is a skin. * - ``Spawn`` - 9 - Asset is a spawn table. * - ``NPC`` - 10 - Asset is related to NPCs (such as quests, vendors, or dialogues). ================================================ FILE: data/enum/ebatterymode.rst ================================================ .. _doc_data_ebatterymode: EBatteryMode ============ The EBatteryMode enumerated type is used to determine how a vehicle battery should behave. This is only used by :ref:`vehicle assets `. Enumerators ``````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - Battery charge remains unchanged. * - ``Burn`` - Battery charge will deplete over time. * - ``Charge`` - Battery charge will replenish over time. ================================================ FILE: data/enum/eitemorigin.rst ================================================ .. _doc_data_eitemorigin: EItemOrigin =========== The EItemOrigin enumerated type is used when spawning items. Enumerators ``````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``World`` - Item origin is the world. * - ``Admin`` - Item origin is an admin command. * - ``Craft`` - Item origin is crafting. * - ``Nature`` - Item origin is nature. ================================================ FILE: data/enum/eitemrarity.rst ================================================ .. _doc_data_eitemrarity: EItemRarity =========== The EItemRarity enumerated type consists of all the possible rarities of in-game content. Note that these are not the same as the item qualities used by Steam Economy items. Enumerators ``````````` .. list-table:: :widths: 20 10 70 :header-rows: 1 * - Named Value - Index - Description * - ``Common`` - 0 - Corresponds to the "Common" (white-colored) rarity. * - ``Uncommon`` - 1 - Corresponds to the "Uncommon" (green-colored) rarity. * - ``Rare`` - 2 - Corresponds to the "Rare" (blue-colored) rarity. * - ``Epic`` - 3 - Corresponds to the "Epic" (purple-colored) rarity. * - ``Legendary`` - 4 - Corresponds to the "Legendary" (pink-colored) rarity. * - ``Mythical`` - 5 - Corresponds to the "Mythical" (red-colored) rarity. ================================================ FILE: data/enum/eitemtype.rst ================================================ .. _doc_data_eitemtype: EItemType ========= The EItemType enumerated type consists of all the possible item types. Enumerators ``````````` .. list-table:: :widths: 20 10 70 :header-rows: 1 * - Named Value - Index - Description * - ``Hat`` - 0 - Corresponds to the "Hat" item type. * - ``Pants`` - 1 - Corresponds to the "Pants" item type. * - ``Shirt`` - 2 - Corresponds to the "Shirt" item type. * - ``Mask`` - 3 - Corresponds to the "Mask" item type. * - ``Backpack`` - 4 - Corresponds to the "Backpack" item type. * - ``Vest`` - 5 - Corresponds to the "Vest" item type. * - ``Glasses`` - 6 - Corresponds to the "Glasses" item type. * - ``Gun`` - 7 - Corresponds to the "Gun" item type. * - ``Sight`` - 8 - Corresponds to the "Sight" item type. * - ``Tactical`` - 9 - Corresponds to the "Tactical" item type. * - ``Grip`` - 10 - Corresponds to the "Grip" item type. * - ``Barrel`` - 11 - Corresponds to the "Barrel" item type. * - ``Magazine`` - 12 - Corresponds to the "Magazine" item type. * - ``Food`` - 13 - Corresponds to the "Food" item type. * - ``Water`` - 14 - Corresponds to the "Water" item type. * - ``Medical`` - 15 - Corresponds to the "Medical" item type. * - ``Melee`` - 16 - Corresponds to the "Melee" item type. * - ``Fuel`` - 17 - Corresponds to the "Fuel" item type. * - ``Tool`` - 18 - Corresponds to the "Tool" item type. * - ``Barricade`` - 19 - Corresponds to the "Barricade" item type. * - ``Storage`` - 20 - Corresponds to the "Storage" item type. * - ``Beacon`` - 21 - Corresponds to the "Beacon" item type. * - ``Farm`` - 22 - Corresponds to the "Farm" item type. * - ``Trap`` - 23 - Corresponds to the "Trap" item type. * - ``Structure`` - 24 - Corresponds to the "Structure" item type. * - ``Supply`` - 25 - Corresponds to the "Supply" item type. * - ``Throwable`` - 26 - Corresponds to the "Throwable" item type. * - ``Grower`` - 27 - Corresponds to the "Grower" item type. * - ``Optic`` - 28 - Corresponds to the "Optic" item type. * - ``Refill`` - 29 - Corresponds to the "Refill" item type. * - ``Fisher`` - 30 - Corresponds to the "Fisher" item type. * - ``Cloud`` - 31 - Corresponds to the "Cloud" item type. * - ``Map`` - 32 - Corresponds to the "Map" item type. * - ``Key`` - 33 - Corresponds to the "Key" item type. * - ``Box`` - 34 - Corresponds to the "Box" item type. * - ``Arrest_Start`` - 35 - Corresponds to the "Arrest_Start" item type. * - ``Arrest_End`` - 36 - Corresponds to the "Arrest_End" item type. * - ``Tank`` - 37 - Corresponds to the "Tank" item type. * - ``Generator`` - 38 - Corresponds to the "Generator" item type. * - ``Detonator`` - 39 - Corresponds to the "Detonator" item type. * - ``Charge`` - 40 - Corresponds to the "Charge" item type. * - ``Library`` - 41 - Corresponds to the "Library" item type. * - ``Filter`` - 42 - Corresponds to the "Filter" item type. * - ``Sentry`` - 43 - Corresponds to the "Sentry" item type. * - ``Vehicle_Repair_Tool`` - 44 - Corresponds to the "Vehicle_Repair_Tool" item type. * - ``Tire`` - 45 - Corresponds to the "Tire" item type. * - ``Compass`` - 46 - Corresponds to the "Compass" item type. * - ``Oil_Pump`` - 47 - Corresponds to the "Oil_Pump" item type. * - ``Vehicle_Paint_Tool`` - 48 - Corresponds to the "Vehicle_Paint_Tool" item type. ================================================ FILE: data/enum/elightingvision.rst ================================================ .. _doc_data_elightingvision: ELightingVision =============== The ELightingVision enumerated type is used to determine the lighting conditions when using certain items, such as :ref:`glasses `. Some assets may only support using specific enumerators. Enumerators ``````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - There is no vision effect, and normal lighting is used. * - ``Military`` - "Military" nightvision lighting is used. When supported by the asset, nightvision color is ``#507814``, and nightvision fog intensity is ``0.25``. * - ``Civilian`` - "Civilian" nightvision lighting is used. When supported by the asset, nightvision color is ``#666666``, and nightvision fog intensity is ``0.5``. * - ``Headlamp`` - "Headlamp" lighting is used. When supported by the asset, this will enable a toggleable light source and allow for using :ref:`PlayerSpotLightConfig ` properties. ================================================ FILE: data/enum/enpcholiday.rst ================================================ .. _doc_data_enpcholiday: ENPCHoliday =========== The ENPCHoliday enumerated type consists of all of the game's recognized holidays or seasonal events. You can find the duration of scheduled seasonal events in the ``Client.log`` file generated after launching the game, or in the ``HolidayUtil.cs`` source file. The start and end times for all holidays are relative to the player's local time, meaning they are affected by timezones. For Lunar New Year, the start and end dates are automatically calculated and the holiday's duration is set in the game's ``Status.json`` file. .. note:: Some assets only support a few of the game's recognized holidays. Notably: Landscape Material Assets only support Halloween, Christmas, and April Fools' Day. Enumerators ``````````` .. list-table:: :header-rows: 1 * - Named Value - Description - Duration * - ``None`` - Represents no holiday or seasonal event. - * - ``Halloween`` - Corresponds to the `Halloween `_ holiday. - October 20, 2025 (00:00) – November 1, 2025 (12:00) * - ``Christmas`` - Corresponds to the `Christmas `_ holiday, and other holidays within the festive season. - December 7, 2025 (00:00) – January 2, 2026 (12:00) * - ``April_Fools`` - Corresponds to the `April Fools' Day `_ holiday. - April 1, 2025 (00:00) – April 1, 2025 (23:59:59) * - ``Valentines`` - Corresponds to the `Valentine's Day `_ holiday. - February 14, 2025 (00:00) – February 14, 2025 (23:59:59) * - ``Pride_Month`` - Corresponds to `Pride Month `_, a month-long observance in June. - June 1, 2025 (00:00) – June 30, 2025 (23:59:59) * - ``Lunar_New_Year`` - Corresponds to the `Lunar New Year `_ holiday. - Varies based on the Chinese calendar, being calculated as the day *before* Lunar New Year to 15 days *after* Lunar New Year. For example: January 28, 2025 (00:00) – February 13, 2025 (23:59:59). * - ``Unturned_Anniversary`` - Corresponds to the game's anniversary on Steam. - July 7, 2025 (00:00) – July 7, 2025 (23:59:59) * - ``Max`` - Only used/implemented in the game's source code – no practical use for game assets. - ================================================ FILE: data/enum/eobjectchart.rst ================================================ .. _doc_data_eobjectchart: EObjectChart ============ The EObjectChart enumerated type is used to determine the how an asset should appear when generating a map's chart view. Most of the enumerators corresponds to a specific pixel coordinate on either the Height_Strip or Layer_Strip of a map's :ref:`Charts.unity3d file `. Enumerators ``````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - Use the default for this asset. * - ``Ground`` - Use (20, 0) from the Height_Strip. * - ``Ignore`` - Skip this asset, and use whatever is underneath. * - ``Highway`` - Use (0, 0) from the Layer_Strip. * - ``Street`` - Use (1, 0) from the Layer_Strip. * - ``Road`` - Use (2, 0) from the Layer_Strip. * - ``Path`` - Use (3, 0) from the Layer_Strip. * - ``Large`` - Use (15, 0) from the Layer_Strip. * - ``Medium`` - Use (16, 0) from the Layer_Strip. * - ``Water`` - Use (0, 0) from the Height_Strip. * - ``Cliff`` - Use (4, 0) from the Layer_Strip. ================================================ FILE: data/enum/eobjecttype.rst ================================================ .. _doc_data_eobjecttype: EObjectType =========== The EObjectType enumerated type consists of all the possible object types. Enumerators ``````````` .. list-table:: :widths: 20 10 70 :header-rows: 1 * - Named Value - Index - Description * - ``Large`` - 0 - Corresponds to the "Large" object type. * - ``Medium`` - 1 - Corresponds to the "Medium" object type. * - ``Small`` - 2 - Corresponds to the "Small" object type. * - ``NPC`` - 3 - Corresponds to the "NPC" object type. * - ``Decal`` - 4 - Corresponds to the "Decal" object type. ================================================ FILE: data/enum/eslottype.rst ================================================ .. _doc_data_eslottype: ESlotType ========= The ESlotType enumerated type is used for item placement in displays or on characters, and determines which item slot(s) an equippable item can be placed in. Some assets may only support using specific enumerators. Enumerators ``````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - Does not correspond to any slot. Equippables can be hotkeyed. * - ``Primary`` - Corresponds to the "Primary" slot. Equippables can be used from the primary slot. * - ``Secondary`` - Corresponds to the "Secondary" slot. Equippables can be used from the primary or secondary slot. * - ``Tertiary`` - Corresponds to the "Tertiary" slot. This is only used by NPCs. * - ``Any`` - Corresponds to any/all item slots. Equippables can be used from any slot, or hotkeyed. ================================================ FILE: data/enum/index.rst ================================================ 🗀 Enumerated Types =================== .. Below is the table-of-content tree for the folder. .. toctree:: :maxdepth: 1 :glob: * ================================================ FILE: data/flag.rst ================================================ .. _doc_data_flag: Flag ==== Some asset types have properties that only look for the presence of a particular key, rather than a key-value pair. These are referred to as **flags**. Their value can be left empty, since flags do not have a value paired to them. For example, item assets check for the ``Pro`` flag. An item asset that included this flag is marked as a Steam economy item. .. code-block:: text Flag1 Flag2 Flag3 ================================================ FILE: data/guid.rst ================================================ .. _doc_data_guid: GUID ==== Globally Unique Identifiers (**GUIDs**) are 32-digit hexadecimal values used to identify assets. They are preferable to file names because the files can be moved without redirectors. A useful tool for manually generating GUIDs is `guidgenerator.com `_. Note that if the GUID property is omitted from an :ref:`asset definition ` file, then the game will automatically assign a random GUID during a successful load. Legacy IDs are 16 bits with a [0, 65535] range, whereas GUIDs are 128 bits with an unimaginably huge range. This allows them to be generated without coordination or registration between developers. ================================================ FILE: data/master-bundle-ptr.rst ================================================ .. _doc_data_masterbundleptr: Master Bundle Pointer ===================== Identifies a Unity asset like a prefab, material or audio clip within a master bundle. In \*.asset files ----------------- ``MasterBundle``: File name of the asset bundle exported from Unity. Should match the ``Asset_Bundle_Name`` configured in the ``MasterBundle.dat`` file. ``AssetPath``: File path of the Unity asset (e.g., \*.prefab, \*.mat, \*.png, or \*.ogg files). This path is relative to the ``Asset_Prefix`` path configured in the ``MasterBundle.dat`` file. .. code-block:: unturnedasset "MyMasterBundlePtr" { "MasterBundle" "core.masterbundle" "AssetPath" "path/to/file.extension" } If the asset default master bundle should be used, then the path can be specified inline: .. code-block:: unturnedasset "MyMasterBundlePtr" "path/to/file.extension" Alternatively, the name of a master bundle can be prefixed to the inline path: .. code-block:: unturnedasset "MyMasterBundlePtr" "core.masterbundle:path/to/file.extension" ================================================ FILE: data/rich-text.rst ================================================ .. _doc_data_richtext: Rich Text ========= Certain text blocks support **rich text** markup. These are tags which modify the appearance of the text for example bold, italics, colors, etc. Which tags are supported depends on the :ref:`doc_glazier` mode being used. Most players will be using the default, uGUI. Extended Tags ------------- These tags are specific to *Unturned*. **\**: New line. Supported in most multi-line text boxes such as dialogue, signs/notes, item descriptions, etc. **\**: Insert the NPC character's name. Only supported in NPC dialogue. **\**: Insert the player character's name. Only supported in NPC dialogue and signs/notes. **\**: Pause dialogue for 0.5 seconds before continuing. Only supported in NPC dialogue. uGUI - TextMesh Pro (default) ----------------------------- For the full list of tags please refer to the TextMesh Pro documentation here: https://docs.unity3d.com/Packages/com.unity.textmeshpro@2.2/manual/RichText.html IMGUI ----- For the full list of tags please refer to the Unity styled text documentation here: https://docs.unity3d.com/2018.3/Documentation/Manual/StyledText.html ================================================ FILE: data/struct/index.rst ================================================ 🗀 Structs ========== .. Below is the table-of-content tree for the folder. .. toctree:: :maxdepth: 1 :glob: * ================================================ FILE: data/struct/playerspotlightconfig.rst ================================================ .. _doc_data_playerspotlightconfig: PlayerSpotLightConfig ===================== The PlayerSpotLightConfig struct contains properties for configuring player spot lights. Certain item assets are able to utilize these properties. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`SpotLight_Enabled ` - :ref:`bool ` - ``true`` * - :ref:`SpotLight_Range ` - :ref:`float32 ` - ``64`` * - :ref:`SpotLight_Angle ` - :ref:`float32 ` - ``90`` * - :ref:`SpotLight_Intensity ` - :ref:`float32 ` - ``1.3`` * - :ref:`SpotLight_Color ` - :ref:`color ` - ``#f5df93`` Property Descriptions ````````````````````` .. _doc_data_playerspotlightconfig:spotlight_enabled: SpotLight_Enabled :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, this item should have a toggleable light source. ---- .. _doc_data_playerspotlightconfig:spotlight_range: SpotLight_Range :ref:`float32 ` ``64`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Range of the light source's beam, measured in meters. ---- .. _doc_data_playerspotlightconfig:spotlight_angle: SpotLight_Angle :ref:`float32 ` ``90`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Angle of the light source's beam, measured in degrees. ---- .. _doc_data_playerspotlightconfig:spotlight_intensity: SpotLight_Intensity :ref:`float32 ` ``1.3`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Intensity of the light source's beam. ---- .. _doc_data_playerspotlightconfig:spotlight_color: SpotLight_Color :ref:`color ` ``#f5df93`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Color of the light source's beam. ================================================ FILE: data/vector3.rst ================================================ .. _doc_data_vector3: Vector3 ======= **Vector3** (or "3D vectors") can either be parsed as a single value containing three :ref:`floats ` (optionally surrounded by parenthesis), or from a dictionary with ``X``, ``Y``, and ``Z`` keys. For example, all three of these would be valid 3D vectors: .. code-block:: text Position 1, 2, 3 Offset (4, 5, 6) Scale { X 7 Y 8 Z 9 } Legacy Parsing -------------- Some older properties have support for the vector3 data type, but can alternatively be written using the legacy method of three separate :ref:`float32 ` properties. Namely, the ``LOD_Center``, ``LOD_Size``, ``Explosion_Min_Force``, ``Explosion_Max_Force``, and ``Center_Of_Mass`` properties have support for both. For example, this would be valid for an older property that supports the legacy format: .. code-block:: text LOD_Size_X 0 LOD_Size_Y -12 LOD_Size_Z -1 ================================================ FILE: img/WorkshopMapIDs.csv ================================================ Workshop Map,File ID A6 Polaris,2898548949 Athens Arena,1454125991 Arid,2683620106 Belgium,1727125581 Buak,3000549606 Bunker Arena,1257784170 California,1905768396 California2,3707778928 Canyon Arena,1850209768 Carpat,1497352180 Cyprus Arena,1647991167 Cyprus Survival,1647986053 Dango,1850228333 Easter Island,1983200271 Escalation,3251926587 Elver,2136497468 France,1975500516 Greece,1702240229 Hawaii,1753134636 Hawaii Assets,1753131903 Ireland,1411633953 Kuwait,2483365750 PEI Arena,2396897717 Rio de Janeiro,3416057692 Rio de Janeiro (Original),1821848824 Washington Arena,2404652624 ================================================ FILE: index.rst ================================================ Unturned Documentation ====================== .. Below is the table-of-content tree for the website, which is hidden from the page but appears in the sidebar. ... The toctree is located at the top of this file, so that chapters are generated properly for the offline downloads. .. toctree:: :hidden: :maxdepth: 1 :caption: About about/getting-started about/launch-options about/steam-workshop .. toctree:: :hidden: :maxdepth: 1 :caption: Introduction to Modding assets/asset-bundles assets/asset-definitions assets/data-file-format assets/asset-validation assets/asset-bundle-custom-data assets/curated-items assets/animation assets/layers assets/mod-hooks assets/unity-upgrade .. toctree:: :hidden: :maxdepth: 1 :caption: Creating Items :glob: items/introduction items/blueprints items/actions items/* .. toctree:: :hidden: :maxdepth: 1 :caption: Creating Vehicles assets/vehicle-asset assets/vehicle-physics-profile-asset assets/vehicle-redirector-asset .. toctree:: :hidden: :maxdepth: 1 :caption: Creating Objects :glob: assets/object-asset assets/material-palette-asset .. toctree:: :hidden: :maxdepth: 1 :caption: NPCs and Logic :glob: npcs/introduction npcs/npc-asset npcs/dialogue-asset npcs/quest-asset npcs/vendor-asset npcs/conditions npcs/rewards npcs/rewards-list-asset npcs/currency-asset .. toctree:: :hidden: :maxdepth: 1 :caption: Creating Miscellaneous Assets assets/airdrop-asset assets/animal-asset assets/character-mesh-replacement assets/crafting-asset assets/crafting-blacklist-asset assets/effect-asset assets/foliage-asset assets/road-asset assets/level-asset assets/mythical-asset assets/outfit-asset assets/physics-material-asset assets/redirector-asset assets/resource-asset assets/server-browser-curation-asset assets/spawn-asset assets/stereo-song-asset assets/tag-asset assets/weather-asset assets/zombie-difficulty-asset .. toctree:: :hidden: :maxdepth: 1 :caption: Mapping mapping/charts mapping/curated-maps mapping/editor-asset-redirectors mapping/favorite-searches mapping/level-batching mapping/level-config mapping/manual-object-culling .. toctree:: :hidden: :maxdepth: 1 :caption: Servers & Programming ★ Setting up a Server ★ Using SteamCMD (Advanced Setup) ★ Server Hosting Rules servers/bookmark-host servers/command-io servers/debugging-exceptions servers/dedicated-workshop-update-monitor servers/fake-ip servers/game-server-login-tokens servers/glazier servers/openmod servers/port-forwarding servers/rocket servers/server-auto-restart servers/server-browser-curation servers/server-codes servers/server-configuration servers/server-update-notifications .. toctree:: :hidden: :maxdepth: 1 :caption: Data Types data/built-in-types data/asset-ptr data/bitmask data/color data/enum/index data/flag data/guid data/master-bundle-ptr data/rich-text data/struct/index data/vector3 .. toctree:: :hidden: :maxdepth: 1 :caption: SDG / Project Info :glob: sdg/source-code sdg/using-git sdg/unity-project sdg/* Welcome to the official documentation for `Unturned `_'s modding and server hosting features! To navigate, use the table of contents in the sidebar or the search function in the top-left corner. Upcoming Features ----------------- You can find modding features under consideration on this Trello board: `Unturned Roadmap `_. The cards on the board aren't ordered in any particular way. i.e., they do not dictate the order of updates. Miscellaneous requests and tasks that may pop up take priority over the roadmap, so it may go a while between progress updates. Several high-priority ideas that don't yet have a solid plan, like a crafting revamp, are not listed on the board. Legacy Tutorials ---------------- Our earliest modding documentation was available through Steam Guides. Although most of these guides have been superseded by our documentation here, some still contain useful information about Unity setup that we have yet to bring over. The useful guides are: - `Items `_: Most of the sub-sections about Unity setup are still relevant. - `Vehicles `_: Information about Unity setup. - `Objects `_: Information about Unity setup. - `Misc. Assets `_: Unity setup for animals, effects, and resources. - `Maps `_: Explaining various features. - `Localization `_ - `Creating 3rd-party Modules `_: Not to be confused with *mods* or *plugins*. - `Uploading Mods to the Steam Workshop `_ - `Upgrading from Unity 5 LTS to Unity 2017 LTS `_: Only relevant for *very* old mods, but lists the important changes between those two versions. There are several official video tutorials available, but many of these have gradually become outdated. They do not accurately represent the current modding features available, or may contain incorrect information, but are listed here for completeness: - `Hosting a Dedicated Server on Windows `_ - `Uploading Skins to the Curated Workshop `_ - `Creating Custom Songs `_ - `Quick Overview of First Version of Foliage Upgrade `_ - `Devkit 101 + Landscapes Overview `_ - `Spawn Tables `_ - `Building Models `_ If you refer to a video tutorial (official or otherwise), we recommend double-checking the information with our written documentation when possible. Offline Downloads ----------------- PDF and Epub versions of the documentation can be `downloaded `_ for offline use. Contributing ------------ Anyone can contribute towards the *Unturned* modding documentation! To submit an issue, visit the `GitHub repository `_. See the `README `_ for more details on how to contribute. ================================================ FILE: items/actions.rst ================================================ .. _doc_item_asset_actions: Actions ======= Context actions appear when a player right-clicks an item from their inventory menu. Some items may have set a of automatically-generated context actions, but additional context actions can be added to any item. The system currently supports adding additional :ref:`blueprint ` actions. Depending on an item's configuration, the game may automatically add context actions for various actions. Game Data File -------------- Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Action_#_Blueprint_#_Index ` - :ref:`uint8 ` - ``0`` * - :ref:`Action_#_Blueprint_#_Name ` - :ref:`string ` - ``""`` * - :ref:`Action_#_Blueprint_#_Link ` - :ref:`flag ` - * - :ref:`Action_#_Blueprints ` - :ref:`uint8 ` - ``0`` * - :ref:`Action_#_Key ` - :ref:`string ` - * - :ref:`Action_#_Source ` - :ref:`uint16 ` - See description * - :ref:`Action_#_Text ` - :ref:`string ` - * - :ref:`Action_#_Tooltip ` - :ref:`string ` - * - :ref:`Action_#_Type ` - :ref:`EActionType ` - * - :ref:`Actions ` - :ref:`uint8 ` - ``0`` .. _doc_item_asset_actions:eactiontype: EActionType Enumeration ``````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``Blueprint`` - Action is linked a crafting blueprint. Property Descriptions ````````````````````` .. _doc_item_asset_actions:action_blueprint_index: Action_#_Blueprint_#_Index :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Index of the blueprint that action should perform. .. note:: ``Action_#_Blueprint_#_Name`` should be used instead of ``Action_#_Blueprint_#_Index`` where possible because the index may change if the item's Blueprints list is reorganized. This requires specifying a ``Name`` in the blueprint. ---- .. _doc_item_asset_actions:action_blueprint_name: Action_#_Blueprint_#_Name :ref:`string ` ``""`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Name of the blueprint that action should perform. This requires specifying a ``Name`` in the blueprint, however. ---- .. _doc_item_asset_actions:action_blueprint_link: Action_#_Blueprint_#_Link :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Action should redirect to the associated blueprint listing in the crafting menu, rather than immediately craft the item. ---- .. _doc_item_asset_actions:action_blueprints: Action_#_Blueprints :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Total number of blueprint indices. ---- .. _doc_item_asset_actions:action_key: Action_#_Key :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::::::::::: Translation key that should be used instead of a custom button name and tooltip. Valid translation keys and their localization can be found in the ``PlayerDashboardInventory.dat`` localization file. Valid keys include: ``Attachments``, ``Craft_Bandage``, ``Craft_Dressing``, ``Craft_Rag``, ``Craft_Seed``, ``Dequip``, ``Drop``, ``Equip``, ``Pickup``, ``Refill``, ``Repair``, ``Salvage``, ``Stack``, ``Store``, ``Take``, and ``Unstack``. This property cannot be used in combination with ``Action_#_Text`` or ``Action_#_Tooltip``. If set, the value of this property will always override any custom button name or tooltip that has been set. ---- .. _doc_item_asset_actions:action_source: Action_#_Source :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: ID of the item to source actions from. Default source is the current item. ---- .. _doc_item_asset_actions:action_text: Action_#_Text :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::::::::: Context button name. If a key matching this value exists in the per-item localization file then that text is shown, otherwise this value is shown as-is. This property is usually used in combination with ``Action_#_Tooltip``. ---- .. _doc_item_asset_actions:action_tooltip: Action_#_Tooltip :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: Context button tooltip. If a key matching this value exists in the per-item localization file then that tooltip is shown, otherwise this value is shown as-is. This property is usually used in combination with ``Action_#_Text``. ---- .. _doc_item_asset_actions:action_type: Action_#_Type :ref:`EActionType ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Type of action to perform. Currently, only the ``Blueprint`` action type exists. ---- .. _doc_item_asset_actions:actions: Actions :ref:`int ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::: Total number of context actions. Default Actions --------------- Depending on the blueprints an item has, some blueprint actions may be automatically added to the item as well. These actions will be linked to the blueprint they were automatically generated from. - When a blueprint only has one supply, with a supply ID of the item itself, an action using the ``Salvage`` localization key is generated. - When a blueprint uses the ``Repair`` type, an action using the ``Repair`` localization key is generated. - When a blueprint uses the ``Refill`` type, an action using the ``Refill`` localization key is generated. ================================================ FILE: items/arrest-end-asset.rst ================================================ .. _doc_item_asset_arrest_end: Arrest End Assets ================= The ItemArrestEndAsset class is used for "releaser" items, which can remove a corresponding ":ref:`catcher `" item that is restraining a player. An example of a vanilla releaser is the `Handcuffs Key `_. Game Data File -------------- Releasers inherit properties from the :ref:`ItemAsset ` class. Any properties from parent classes that are required are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Arrest_End`` * - :ref:`ItemAsset ` - :ref:`Useable ` - ``Arrest_End`` Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Recover ` - :ref:`uint16 ` - ``0`` Property Descriptions ````````````````````` .. _doc_item_asset_arrest_end:recover: Recover :ref:`uint16 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a corresponding :ref:`catcher ` item that can be unlocked with this item. ================================================ FILE: items/arrest-start-asset.rst ================================================ .. _doc_item_asset_arrest_start: Arrest Start Assets =================== The ItemArrestStartAsset class is used for "catcher" items, which can restrain a player. Its sister item, the ":ref:`releaser `", can be used to unlock restraints. Some examples of vanilla catchers include the `Handcuffs `_ and `Cable Tie `_. Game Data File -------------- Catchers inherit properties from the :ref:`ItemAsset ` class. Any properties from parent classes that are required are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Arrest_Start`` * - :ref:`ItemAsset ` - :ref:`Useable ` - ``Arrest_Start`` Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Strength ` - :ref:`uint16 ` - ``0`` Property Descriptions ````````````````````` .. _doc_item_asset_arrest_start:strength: Strength :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Number of times a player must lean in order to break free from their restraints. ================================================ FILE: items/backpack-asset.rst ================================================ .. _doc_item_asset_backpack: Backpack Assets =============== Backpacks are created from the ItemBackpackAsset class. They can be worn by players and zombies, and occupy the player's "backpack" slot. Game Data File -------------- The ItemBackpackAsset class inherits properties from the :ref:`ItemBagAsset ` class. Properties that are required (or recommended) are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Backpack`` * - :ref:`ItemAsset ` - :ref:`Useable ` - ``Clothing`` Some inherited properties behave differently when used by this class. Notably, these are: #. | :ref:`Armor ` (from :ref:`ItemClothingAsset `). Backpacks do not cover any body part(s) when worn, so this property has no effect. #. | :ref:`InventoryAudio ` (from :ref:`ItemAsset `). Defaults to ``Sounds/Inventory/LightMetalEquipment.asset`` when :ref:`Width ` or :ref:`Height ` are less than ``3``. To ``Sounds/Inventory/MediumMetalEquipment.asset`` when less than ``6``. Otherwise, to ``Sounds/Inventory/HeavyMetalEquipment.asset``. Properties `````````` Backpacks have no unique properties. Refer to parent classes for additional properties instead. ================================================ FILE: items/bag-asset.rst ================================================ .. _doc_item_asset_bag: Bag Assets ========== The ItemBagAsset class is a base class that other classes are derived from. It is unusable on its own. Game Data File -------------- The ItemBagAsset class inherits properties from the :ref:`ItemClothingAsset ` class. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Height ` - :ref:`uint8 ` - ``0`` * - :ref:`Width ` - :ref:`uint8 ` - ``0`` Property Descriptions ````````````````````` .. _doc_item_asset_bag:height: Height :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::: Number of rows (vertical storage space). ---- .. _doc_item_asset_bag:width: Width :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::: Number of columns (horizontal storage space). ================================================ FILE: items/barrel-asset.rst ================================================ .. _doc_item_asset_barrel: Barrel Assets ============= Barrels (or "barrel attachments") are created from the ItemBarrelAsset class. Barrel attachments are inventory items that can be attached to ranged weapons. This inherits the :ref:`CaliberAsset ` class. Game Data File -------------- Barrel attachments inherit properties from the CaliberAsset class, which in turn inherits properties from the ItemAsset class. Properties that are required to be included are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Barrel`` Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Braked ` - :ref:`flag ` - * - :ref:`Durability ` - :ref:`uint8 ` - ``0`` * - :ref:`Gunshot_Rolloff_Distance_Multiplier ` - :ref:`float32 ` - See description * - :ref:`Silenced ` - :ref:`flag ` - * - :ref:`Volume ` - :ref:`float32 ` - ``1`` Property Descriptions ````````````````````` .. _doc_item_asset_barrel:ballistic_drop: Ballistic_Drop :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: .. note:: Moved to :ref:`Caliber Asset `. ---- .. _doc_item_asset_barrel:braked: Braked :ref:`flag ` :::::::::::::::::::::::::::::::::: Muzzle flash should be hidden. ---- .. _doc_item_asset_barrel:durability: Durability :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Amount of quality lost after each firing of the ranged weapon. When this value is greater than ``0``, the item always has a visible item quality shown. ---- .. _doc_item_asset_barrel:gunshot_rolloff_distance_multiplier: Gunshot_Rolloff_Distance_Multiplier :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on gunshot rolloff distance. Defaults to ``0.5`` if ``Silenced``, otherwise to ``1``. ---- .. _doc_item_asset_barrel:silenced: Silenced :ref:`flag ` :::::::::::::::::::::::::::::::::::: Alerts should not be generated when firing. ---- .. _doc_item_asset_barrel:volume: Volume :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on gunfire sound volume. This is often used alongside with ``Silenced``, but doing so is not required. ================================================ FILE: items/barricade-asset.rst ================================================ .. _doc_item_asset_barricade: Barricade Assets ================ Barricades are created from the ItemBarricadeAsset class. They can be placed by players or in the level editor. This inherits the :ref:`PlaceableAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Barricade``): When intending to use a child class, refer to that class's documentation instead for the proper enumerator to use. **Useable** *enum* (``Barricade``) **Build** *enum* (``Barrel_Rain``, ``Barricade``, ``Barricade_Wall``, ``Beacon``, ``Bed``, ``Cage``, ``Campfire``, ``Charge``, ``Claim``, ``Clock``, ``Door``, ``Farm``, ``Fortification``, ``Freeform``, ``Gate``, ``Generator``, ``Glass``, ``Hatch``, ``Ladder``, ``Library``, ``Mannequin``, ``Note``, ``Oil``, ``Oven``, ``Oxygenator``, ``Safezone``, ``Sentry_Freeform``, ``Sentry``, ``Shutter``, ``Sign_Wall``, ``Sign``, ``Spike``, ``Spot``, ``Stereo``, ``Storage_Wall``, ``Storage``, ``Tank``, ``Torch``, ``Vehicle``, ``Wire``): Some values may not function properly without using a child class instead. When intending to use a child class, refer to that class's documentation instead for the proper enumerator to use. **ID** *uint16*: Must be a unique identifier. **InventoryAudio** :ref:`Master Bundle Pointer `: See :ref:`ItemAsset ` for full documentation. Defaults to ``Sounds/Inventory/Seeds.asset`` if the name contains the word "Seed", to ``Sounds/Inventory/SmallMetal.asset`` if the name contains the word "Metal", to ``Sounds/Inventory/LightMetalEquipment.asset`` if either ``Size_X`` or ``Size_Y`` value is equal to 1, to ``Sounds/Inventory/MediumMetalEquipment.asset`` if either ``Size_X`` or ``Size_Y`` value is less than or equal to 2, or ``Sounds/Inventory/HeavyMetalEquipment.asset`` if none of the criteria is met. Barricade Asset Properties -------------------------- **Allow_Collision_While_Animating** *bool*: Whether or not animated interactables should have collision during their animation. If true, animated colliders are enabled while playing the animation even when a player is overlapping. Be wary when enabling this, as it can allow for physics-based exploits such as those involving doors. Defaults to false. **Allow_Placement_Inside_Clip_Volumes** *bool*: If true, the barricade can be placed inside of player clip volumes. Defaults to false, except when using ``Build Charge``. **Allow_Placement_On_Vehicle** *bool*: If true, this barricade can be placed on vehicles. Defaults to true, except when using ``Build Bed``, ``Build Sentry``, or ``Build Sentry_Freeform``. .. note:: ``Armor_Falloff*`` properties are applicable to Animals, Objects, Resources, Structures, and Vehicles as well. (TODO: move into their own doc?) **Armor_FalloffMaxRange** *float*: Ranged damage (guns) from greater than this distance finishes decreasing toward ``Armor_FalloffMultiplier``. Defaults to -1, in which case armor falloff is ignored. **Armor_FalloffRange** *float*: Ranged damage (guns) from greater than this distance begins decreasing toward ``Armor_FalloffMultiplier``. Defaults to ``Armor_FalloffMaxRange`` (immediate decrease, no transition). **Armor_FalloffMultiplier** *float*: [0, 1] normalized percentage of incoming damage to apply past ``Armor_FalloffMaxRange``. **Armor_Tier** *enum* (``Low``, ``High``): Barricade armor can either be low-tier or high-tier. Defaults to low-tier, except when the barricade's name contains the word "Metal". By default, barricades with low-tier armor take 100% of the damage they receive, while barricades with high-tier armor take 50% of the damage they receive. These multipliers can be configured in the `gameplay config `_. **Bypass_Claim** *bool*: When ``true``, this can be placed inside someone else's claimed area. This property used to be a *flag*, and using it as such is still supported. Defaults to false, except when using ``Build Charge``. **Bypass_Pickup_Ownership** *bool*: If true, non-owners of the placed barricade can pick it up. Defaults to false, except when using ``Build Charge``. **Can_Be_Damaged** *bool*: If true, this barricade can be damaged. Defaults to true. **CanVehicleHookWhileAttached** *bool*: By default, vehicles with "hooks" (such as the Skycrane) cannot pick up vehicles with barricades attached. If all barricades on the vehicle set this to ``true`` then the vehicle *can* be picked up. Defaults to ``false``. .. warning:: In the 3.24.7.0 update notes **CanVehicleHookWhileAttached** was mistakenly referred to as **CanParentVehicleBePickedUp**. In the next update both properties will work, but for the meantime **CanVehicleHookWhileAttached** should be used instead. **Can_Zombies_Target** *bool*: If true, this item is eligible for zombies to detect and attack when stuck. Defaults to true. **Eligible_For_Pooling** *bool*: If true, this barricade is eligible for object pooling. Some barricades may not reset properly when pooling is enabled. Defaults to true, except when using ``Build Beacon``. **Explosion** :ref:`GUID ` or *uint16*: GUID or legacy ID of :ref:`EffectAsset ` to play when destroyed. When using ``Build Vehicle``, this is instead the GUID or legacy ID of the vehicle that should be spawned. **Has_Clip_Prefab** *bool*: Whether or not the barricade has a Clip.prefab. If the barricade should use the same prefab on the server as on the client, set to false. For example, most official content uses ``Has_Clip_Prefab false``. Defaults to true. **Health** *uint16*: Total health value. Defaults to 0. **Locked** *flag*: Only the placed barricade's owner(s) can interact with it. **Offset** *float*: In meters, the distance above the ground the barricade is placed. **PlacementAudioClip** :ref:`Master Bundle Pointer `: AudioClip to play when the barricade is placed. **PlacementPreviewPrefab** :ref:`Master Bundle Pointer `: Overrides the placement preview model spawned when this item is held. **Proof_Explosion** *flag*: Immune to area-of-effect explosive damage. **Radius** *float*: In meters, the radius around the barricade the must be clear in order for it to be placeable. **Range** *float*: In meters, the maximum distance away the barricade can be placed from the player. **RequiresHeatSourceCraftingTagConversion** *bool*: Applicable to ``Oven``, ``Torch``, and ``Campfire`` Build types. Defaults to true. Performs the following modifications during load for backwards compatibility: #. Adds the vanilla Heat Source tag (``20f30322bbcc4b01a4f116d22b24c21a``) to PlaceableProvidesCraftingTags if empty. #. Adds a Crafting Tag Modifier component to the Fire child game object with Mode Remove, Activation Requirement Invert, and Tag ``20f30322bbcc4b01a4f116d22b24c21a``. This removes the Heat Source tag when Fire is inactive. #. Adds a Crafting Tag Provider component to the Barricade game object with Modifiers set to the component added to Fire. **Salvage_Duration_Multiplier** *float*: Multiplier on how long it takes to salvage this barricade. Setting this to a larger number will cause salvaging to take longer. Defaults to 1. **Unpickupable** *flag*: Disables the ability to pick up a placed barricade. For example, the `Horde Beacon `_ uses this flag. **Unrepairable** *flag*: Cannot be repaired by a :ref:`MeleeAsset ` with the ``Repair`` flag. For example, the `Blowtorch `_ would not be able to repair this barricade. **Unsalvageable** *flag*: Salvaging a damaged barricade yields no partial resources. For example, `small glass plates `_ use this flag. **Unsaveable** *flag*: This barricade is excluded from being saved. For example, carepackages use this flag. **Use_Water_Height_Transparent_Sort** *flag*: Useful for transparent barricades, such as glass. **Vulnerable** *flag*: The barricade can be damaged by lower-power weapons that do not have the ``Invulnerable`` flag. ================================================ FILE: items/beacon-asset.rst ================================================ .. _doc_item_asset_beacon: Beacon Assets ============= Beacons are created from the ItemBeaconAsset class. Placing the beacon will start a zombie horde event, which can be completed by killing a predetermined number of zombies before the beacon is destroyed. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Beacon``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Beacon``) **ID** *uint16*: Must be a unique identifier. Beacon Asset Properties ----------------------- **Wave** *uint16*: Number of zombies that must be killed to complete the beacon. If there are not enough zombies in the area for the horde event to be completed, zombies will respawn continuously. The final zombie spawned by a horde event is guaranteed to be a Mega Zombie. Defaults to 0. **Rewards** *byte*: Number of items to drop upon successfully completing the beacon. When using ``Enable_Participant_Scaling true``, the number of rewards will scale based on the number of participants. Defaults to 0. **Reward_ID** *uint16*: Legacy ID of the spawn table to use for the rewarded items. Defaults to 0. **Enable_Participant_Scaling** *bool*: Whether or not zombie health, and rewards dropped, should scale based on the number of players. Zombie health scales linearly, which can be represented by ``(Initial Participants) × 1.5``. Reward scaling has diminishing returns, with an equivalent formula being ``7 * sqrt(Initial Participants)``. Defaults to true. ================================================ FILE: items/blueprints.rst ================================================ .. _doc_item_asset_blueprints: Blueprints ========== Blueprints can be added to items. These function as "crafting recipes", which allow players to craft other items, or even modify the state of the current item. Blueprints are not restricted to affecting the item they have been added to, and a blueprint's inputs and outputs can consist entirely of unrelated items. :ref:`Context actions ` are able to reference blueprints. Depending on the type of blueprint added to the item, the game may automatically generate a corresponding context action as well. Game Data File -------------- The ``Blueprints``, ``Blueprint_#_Type``, ``Blueprint_#_Supplies``, and ``Blueprint_#_Supply_#_ID`` properties are required by all blueprints. Blueprints also require that an output has been configured. There are two methods available for configuring an output. When a blueprint only needs to output one item ID, the ``Blueprint_#_Products`` and ``Blueprint_#_Product`` properties can be used. Alternatively, blueprints can use the ``Blueprint_#_Outputs``, ``Blueprint_#_Output_#_ID``, and ``Blueprint_#_Output_#_Amount`` properties to output multiple, different item IDs. It is very common that a blueprint will also use the ``Blueprint_#_Build``, ``Blueprint_#_Tool``, or ``Blueprint_#_Skill`` properties. Other properties for blueprints have more niche uses, and are less common. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Blueprint_#_Build ` - :ref:`doc_data_guid` or :ref:`uint16 ` - * - :ref:`Blueprint_#_Level ` - :ref:`uint8 ` - ``0`` * - :ref:`Blueprint_#_Map ` - :ref:`string ` - * - :ref:`Blueprint_#_Origin ` - :ref:`doc_data_eitemorigin` - ``Craft`` * - :ref:`Blueprint_#_Output_#_Amount ` - :ref:`uint8 ` - ``0`` * - :ref:`Blueprint_#_Output_#_ID ` - :ref:`uint16 ` - ``0`` * - :ref:`Blueprint_#_Output_#_Origin ` - :ref:`doc_data_eitemorigin` - ``Craft`` * - :ref:`Blueprint_#_Outputs ` - :ref:`uint8 ` - ``0`` * - :ref:`Blueprint_#_Product ` - :ref:`uint16 ` - See description * - :ref:`Blueprint_#_Products ` - :ref:`uint8 ` - ``1`` * - :ref:`Blueprint_#_Searchable ` - :ref:`bool ` - ``true`` * - :ref:`Blueprint_#_Skill ` - :ref:`EBlueprintSkill ` - ``None`` * - :ref:`Blueprint_#_State_Transfer ` - :ref:`flag ` - * - :ref:`Blueprint_#_State_Transfer_Delete_Attachments ` - :ref:`bool ` - ``false`` * - :ref:`Blueprint_#_Supplies ` - :ref:`uint8 ` - ``0`` * - :ref:`Blueprint_#_Supply_#_AllowEmpty ` - :ref:`bool ` - ``false`` * - :ref:`Blueprint_#_Supply_#_Amount ` - :ref:`uint8 ` - ``0`` * - :ref:`Blueprint_#_Supply_#_Critical ` - :ref:`flag ` - * - :ref:`Blueprint_#_Supply_#_ID ` - :ref:`uint16 ` - * - :ref:`Blueprint_#_Supply_#_Prioritization ` - :ref:`enum ` - * - :ref:`Blueprint_#_Tool ` - :ref:`uint16 ` - ``0`` * - :ref:`Blueprint_#_Tool_Critical ` - :ref:`flag ` - * - :ref:`Blueprint_#_Type ` - :ref:`EBlueprintType ` - * - :ref:`Blueprints ` - :ref:`uint8 ` - ``0`` .. _doc_item_asset_blueprints:eblueprinttype_enumeration: EBlueprintType Enumeration `````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``Ammo`` - Blueprint appears in the "Ammunition" tab. * - ``Apparel`` - Blueprint appears in the "Apparel" tab. * - ``Barricade`` - Blueprint appears in the "Barricades" tab. * - ``Furniture`` - Blueprint appears in the "Furniture" tab. * - ``Gear`` - Blueprint appears in the "Gear" tab. * - ``Repair`` - Blueprint appears in the "Repair" tab. * - ``Structure`` - Blueprint appears in the "Structures" tab. * - ``Supply`` - Blueprint appears in the "Supplies" tab. * - ``Tool`` - Blueprint appears in the "Tools" tab. * - ``Utilities`` - Blueprint appears in the "Utilities" tab. .. _doc_item_asset_blueprints:eblueprintskill_enumeration: EBlueprintSkill Enumeration ``````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - No skill is required. * - ``Craft`` - "Crafting" skill is required. * - ``Cook`` - "Cooking" skill is required. * - ``Repair`` - "Engineer" skill is required. Property Descriptions ````````````````````` .. _doc_item_asset_blueprints:blueprint_#_build: Blueprint_#_Build :ref:`doc_data_guid` or :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of an audio effect to play upon crafting. ---- .. _doc_item_asset_blueprints:blueprint_#_level: Blueprint_#_Level :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If the blueprint requires a skill, its level must be equal to this value. This property is used in conjunction with ``Blueprint_#_Skill``. ---- .. _doc_item_asset_blueprints:blueprint_#_map: Blueprint_#_Map :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Name of a map that this blueprint is restricted to. The blueprint will only be visible while on this map. For other maps, the blueprint is hidden from view. ---- .. _doc_item_asset_blueprints:blueprint_#_origin: Blueprint_#_Origin :ref:`doc_data_eitemorigin` ``Craft`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Set the item origin. For example, setting the origin to ``Admin`` will cause items to spawn at full quality. This property requires ``Blueprint_#_Product``. ---- .. _doc_item_asset_blueprints:blueprint_#_output_#_amount: Blueprint_#_Output_#_Amount :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Quantity of the product created. For example, a quantity value of ``2`` would create two of the item specified in ``Blueprint_#_Output_#_ID``. ---- .. _doc_item_asset_blueprints:blueprint_#_output_#_id: Blueprint_#_Output_#_ID :ref:`uint16 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of an item created as a product (i.e., an output that is provided after crafting the blueprint). This property requires ``Blueprint_#_Outputs``. ---- .. _doc_item_asset_blueprints:blueprint_#_output_#_origin: Blueprint_#_Output_#_Origin :ref:`doc_data_eitemorigin` ``Craft`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Set the item origin. For example, setting the origin to ``Admin`` will cause items to spawn at full quality. This property requires ``Blueprint_#_Output_#_ID``. ---- .. _doc_item_asset_blueprints:blueprint_#_outputs: Blueprint_#_Outputs :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Total number of ``Blueprint_#_Output_#_ID`` properties that have been configured. ---- .. _doc_item_asset_blueprints:blueprint_#_product: Blueprint_#_Product :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of the item created as the product (i.e., an output that is provided after crafting the blueprint). To output multiple *different* items, refer to the ``Blueprint_#_Outputs`` and ``Blueprint_#_Output_#_ID`` properties instead. When left unconfigured, this property will default to the value of the parent item's ``ID`` value. ---- .. _doc_item_asset_blueprints:blueprint_#_products: Blueprint_#_Products :ref:`uint8 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Quantity of the product created. For example, a quantity value of ``2`` would create two of the item specified in ``Blueprint_#_Product``. This property requires that ``Blueprint_#_Product`` has been set. ---- .. _doc_item_asset_blueprints:blueprint_#_searchable: Blueprint_#_Searchable :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, this blueprint is visible in the search results even when the player lacks the required items. This property can be used to hide blueprints intended for debugging that are not acquirable through normal gameplay. ---- .. _doc_item_asset_blueprints:blueprint_#_skill: Blueprint_#_Skill :ref:`EBlueprintSkill ` ``None`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The player must have leveled the specified skill in order to craft this blueprint. When set to ``Cook``, the player will also need to be next to a heat source (such as a lit Campfire). This property is used in conjunction with ``Blueprint_#_Level``. ---- .. _doc_item_asset_blueprints:blueprint_#_state_transfer: Blueprint_#_State_Transfer :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Transfer the current state of any supplies to the product, when applicable. For example, some states that can be transferred include: amount (e.g., rounds in an ammunition box), quality percentage, selected firing mode, or fuel units (e.g., from a gas can). ---- .. _doc_item_asset_blueprints:blueprint_#_state_transfer_delete_attachments: Blueprint_#_State_Transfer_Delete_Attachments :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true`` and ``State_Transfer`` is enabled, any output guns will have all of their attachments deleted. ---- .. _doc_item_asset_blueprints:blueprint_#_supplies: Blueprint_#_Supplies :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Total number of ``Blueprint_#_Supply_#_ID`` properties that have been configured. ---- .. _doc_item_asset_blueprints:blueprint_#_supply_#_allowempty: Blueprint_#_Supply_#_AllowEmpty :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, items with an "amount" of zero—such as empty magazines—are treated as an amount of one. In vanilla this is used to enable salvaging empty magazines. ---- .. _doc_item_asset_blueprints:blueprint_#_supply_#_amount: Blueprint_#_Supply_#_Amount :ref:`uint8 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Quantity of the supply required. For example, a quantity value of ``2`` would require two of the item specified in ``Blueprint_#_Supply_#_ID``. ---- .. _doc_item_asset_blueprints:blueprint_#_supply_#_critical: Blueprint_#_Supply_#_Critical :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The blueprint is only visible while the player has this supply. This property requires ``Blueprint_#_Supply_#_ID``. ---- .. _doc_item_asset_blueprints:blueprint_#_supply_#_id: Blueprint_#_Supply_#_ID :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of an item that is required as a supply (i.e., an input that is consumed when crafting the blueprint). This property requires ``Blueprint_#_Supplies``. This property can also be set to a string value of ``this``, which will use the the owning item's legacy ID. Useful for salvaging blueprints to avoid accidentally writing the wrong ID. ---- .. _doc_item_asset_blueprints:blueprint_#_supply_#_prioritization: Blueprint_#_Supply_#_Prioritization :ref:`enum ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls which items are used first. Can be set to ``LowestAmount`` or ``LowestQuality``. - ``LowestAmount`` sorts items by their amount (e.g., number of bullets in magazine) from lowest to highest, and consumes the emptiest ones first. - ``LowestQuality`` sorts items by their quality from lowest (0%) to highest (100%), and consumes those nearest 0% first. ``AMMO`` type blueprints default to ``LowestAmount``, otherwise defaults to ``LowestQuality``. ---- .. _doc_item_asset_blueprints:blueprint_#_tool: Blueprint_#_Tool :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of an item that is required as a "tool" for this blueprint. This item is not consumed when the blueprint is crafted. ---- .. _doc_item_asset_blueprints:blueprint_#_tool_critical: Blueprint_#_Tool_Critical :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: If the blueprint requires a tool, it will only be visible while the player has that tool. This property requires ``Blueprint_#_Tool``. ---- .. _doc_item_asset_blueprints:blueprint_#_type: Blueprint_#_Type :ref:`EBlueprintType ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This value determines which tab of the crafting menu that this blueprint appears under. All blueprints require that this has been configured. ---- .. _doc_item_asset_blueprints:blueprints: Blueprints :ref:`int ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Total number of blueprints. All blueprints require that this has been configured. Conditions and Rewards `````````````````````` Blueprints can use quest conditions and rewards. A common usage is to make it so a blueprint is only available during a seasonal event. For more information, refer to the documentation for :ref:`Conditions ` and :ref:`Rewards ` respectively. Blueprint conditions and rewards are prefixed with ``Blueprint_#_``. For example, ``Blueprint_0_Condition_0_Type Holiday``. Game Data File v2 ----------------- .. warning:: Under construction! We might move this to a different page. The game can auto-convert most blueprints to this new format! For more information, please refer to :ref:`the ResaveAssets launch option `. Starting with version 3.25.5.0, Blueprints can be specified as a :ref:`list ` rather than prefixing each property with ``Blueprint_#_``. For example: .. code-block:: unturneddat Blueprints [ { // First blueprint properties } { // Second blueprint properties } ] Each blueprint dictionary has the following properties: Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`CategoryTag ` - :ref:`Asset Pointer ` to :ref:`doc_assets_tag` - * - :ref:`Conditions ` - :ref:`doc_npc_asset_conditions` - * - :ref:`Effect ` - :ref:`Asset Pointer ` to :ref:`doc_assets_effect` - * - :ref:`InputItems ` - :ref:`list ` of :ref:`doc_item_asset_blueprints_inputitem` - * - :ref:`Map ` - :ref:`string ` - ``""`` * - :ref:`Name ` - :ref:`string ` - ``""`` * - :ref:`Operation ` - :ref:`EBlueprintOperation ` - ``None`` * - :ref:`OutputItems ` - :ref:`list ` of :ref:`doc_item_asset_blueprints_outputitem` - * - :ref:`RequiresNearbyCraftingTags ` - :ref:`list ` of :ref:`Asset Pointer ` to :ref:`doc_assets_tag` - * - :ref:`RequiresStaticTags ` - :ref:`list ` of :ref:`Asset Pointer ` to :ref:`doc_assets_tag` - * - :ref:`Rewards ` - :ref:`doc_npc_asset_rewards` - * - :ref:`Searchable ` - :ref:`bool ` - ``true`` * - :ref:`Skill ` - :ref:`EBlueprintSkill ` - ``None`` * - :ref:`Skill_Level ` - :ref:`int32 ` - ``0`` * - :ref:`StateTransfer ` - :ref:`bool ` - ``false`` * - :ref:`StateTransfer_DeleteAttachments ` - :ref:`bool ` - ``false`` * - :ref:`Type ` - :ref:`EBlueprintType ` - Deprecated. * - :ref:`VisibleWithUnmetConditions ` - :ref:`bool ` - ``false`` .. _doc_item_asset_blueprints:eblueprintoperation_enumeration: EBlueprintOperation Enumeration ``````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - No special modification. * - ``RepairTargetItem`` - Restore target item to full quality. * - ``FillTargetItem`` - Transfer amount from first input item to target item. ---- .. _doc_item_asset_blueprints:blueprint_v2_categorytag: CategoryTag :ref:`Asset Pointer ` to :ref:`doc_assets_tag` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Determines which category the blueprint appears under in the crafting menu. Enables the creation of custom categories. This replaces the ``Type`` property which acted as both a hardcoded category and modified behavior of crafting. ---- .. _doc_item_asset_blueprints:blueprint_v2_conditions: Conditions :ref:`doc_npc_asset_conditions` :::::::::::::::::::::::::::::::::::::::::: NPC conditions which must be met before the blueprint can be crafted. .. note:: By default, the blueprint will be hidden until all of the conditions are met. If you have configured display text for your conditions you can enable :ref:`VisibleWithUnmetConditions `. ---- .. _doc_item_asset_blueprints:blueprint_v2_effect: Effect :ref:`Asset Pointer ` to :ref:`doc_assets_effect` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: An effect to play upon successfully crafting. ---- .. _doc_item_asset_blueprints:blueprint_v2_inputitems: InputItems :ref:`list ` of :ref:`doc_item_asset_blueprints_inputitem` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Required ingredients/supplies needed to craft this blueprint. ---- .. _doc_item_asset_blueprints:blueprint_v2_map: Map :ref:`string ` ``""`` ::::::::::::::::::::::::::::::::::::::::::::::::: Name of a map that this blueprint is restricted to. The blueprint will only be visible while on this map. For other maps, the blueprint is hidden from view. ---- .. _doc_item_asset_blueprints:blueprint_v2_name: Name :ref:`string ` ``""`` :::::::::::::::::::::::::::::::::::::::::::::::::: Optional case-sensitive identifier in list of blueprints. Can be used, for example, to reference this blueprint from a context menu action or a list of prohibited blueprints. ---- .. _doc_item_asset_blueprints:blueprint_v2_operation: Operation :ref:`EBlueprintOperation ` ``None`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls what blueprint does with input items. ---- .. _doc_item_asset_blueprints:blueprint_v2_outputitems: OutputItems :ref:`list ` of :ref:`doc_item_asset_blueprints_outputitem` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Items created by this blueprint. ---- .. _doc_item_asset_blueprints:blueprint_v2_requiresnearbycraftingtags: RequiresNearbyCraftingTags :ref:`list ` of :ref:`Asset Pointer ` to :ref:`doc_assets_tag` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: :ref:`doc_assets_tag` that must be available from nearby crafting tag providers (workstations). For example, to require both Chemical Mixing and Workbench: .. code-block:: unturneddat RequiresNearbyCraftingTags [ // Chemical Mixing 99896da563a748148460c67b9962874f // Workbench 7b82c125a5a54984b8bb26576b59e977 ] ---- .. _doc_item_asset_blueprints:blueprint_v2_requiresstatictags: RequiresStaticTags :ref:`list ` of :ref:`Asset Pointer ` to :ref:`doc_assets_tag` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Similar to ``RequiresNearbyCraftingTags``, but only checked once during level startup. Can test for :ref:`doc_assets_level` ``Tags``. For example, rather than using the ``Map`` property to test for a level by name, the level can signal it supports a set of blueprints with a tag. Vanilla makes the following tags available: .. code-block:: unturneddat "73eb818d1aa044c7bb4e61b8f9b37a3c" // Building In Safezones Allowed "f663677b88de40ec80ff36b0c1cae544" // Not-singleplayer "d7bd989414644b19b3299be0c6fab5f0" // Singleplayer ---- .. _doc_item_asset_blueprints:blueprint_v2_rewards: Rewards :ref:`doc_npc_asset_rewards` :::::::::::::::::::::::::::::::::::: NPC rewards granted when crafting this blueprint. ---- .. _doc_item_asset_blueprints:blueprint_v2_searchable: Searchable :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, this blueprint is visible in the search results even when the player lacks the required items. This property can be used to hide blueprints intended for debugging that are not acquirable through normal gameplay. ---- .. _doc_item_asset_blueprints:blueprint_v2_skill: Skill :ref:`EBlueprintSkill ` ``None`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The player must have leveled the specified skill in order to craft this blueprint. This property is used in conjunction with ``Skill_Level``. ---- .. _doc_item_asset_blueprints:blueprint_v2_skill_level: Skill_Level :ref:`int32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: If the blueprint requires a skill, its level must be greater than or equal to this value. This property is used in conjunction with ``Skill``. ---- .. _doc_item_asset_blueprints:blueprint_v2_statetransfer: StateTransfer :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Transfer the current state the first input item to the product, when applicable. For example, some states that can be transferred include: amount (e.g., rounds in an ammunition box), quality percentage, selected firing mode, or fuel units (e.g., from a gas can). ---- .. _doc_item_asset_blueprints:blueprint_v2_statetransfer_deleteattachments: StateTransfer_DeleteAttachments :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true`` and ``StateTransfer`` is enabled, any output guns will have all of their attachments deleted. ---- .. _doc_item_asset_blueprints:blueprint_v2_type: Type :ref:`EBlueprintType ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Should not be used. Type acted as both a hardcoded category and modified behavior of crafting. These have been separated into the ``CategoryTag`` and ``Operation`` properties instead. ---- .. _doc_item_asset_blueprints:blueprint_v2_visiblewithunmetconditions: VisibleWithUnmetConditions :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, blueprint can become visible in the crafting list even when NPC conditions are not met. This should typically only be enabled if all conditions are configured to be visible in the details panel. Otherwise, the default "conditions unmet" label isn't very informative for players. ================================================ FILE: items/blueprints_inputitem.rst ================================================ .. _doc_item_asset_blueprints_inputitem: Blueprint Input Items ===================== Configuration for a required ingredient item in a :ref:`blueprint `. Value Format ------------ For straightforward cases, a simple one-liner format is supported: - {ID} - {ID} x {Amount} - this - this x {Amount} For examples: .. code-block:: unturneddat // Canned Beans: 78fefdd23def4ab6ac8301adfcc3b2d4 // Or, using Canned Beans' legacy ID: 13 // Two cans of beans: 13 x 2 // Owning asset: this // Two of owning asset: this x 2 Dictionary Format ----------------- Unlike the shorter format above, using these properties requires the ``{ }`` :ref:`dictionary ` format. For example: .. code-block:: unturneddat InputItems [ { // First input item properties } { // Second input item properties } ] Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Amount ` - :ref:`uint8 ` - ``1`` * - :ref:`AllowEmpty ` - :ref:`bool ` - ``false`` * - :ref:`AllowFull ` - :ref:`bool ` - ``true`` * - :ref:`AllowMaxQuality ` - :ref:`bool ` - ``true`` * - :ref:`CountEmptyAsOne ` - :ref:`bool ` - ``false`` * - :ref:`CountingMethod ` - :ref:`ECraftingInputCountingMethod ` - See description * - :ref:`Critical ` - :ref:`bool ` - ``false`` * - :ref:`Delete ` - :ref:`bool ` - ``true`` * - :ref:`ID ` - :ref:`Asset Pointer ` to :ref:`Item ` - * - :ref:`Prioritization ` - :ref:`ECraftingInputPrioritization ` - See description .. _doc_item_asset_blueprints_inputitem:ecraftinginputprioritization_enumeration: ECraftingInputPrioritization Enumeration ```````````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``LowestAmount`` - Sort items with lowest "amount" to front of list. * - ``HighestAmount`` - Sort items with highest "amount" to front of list. * - ``LowestQuality`` - Sort items with lowest quality% to front of list. * - ``HighestQuality`` - Sort items with highest quality% to front of list. .. _doc_item_asset_blueprints_inputitem:ecraftinginputcountingmethod_enumeration: ECraftingInputCountingMethod Enumeration ```````````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``TotalItems`` - Sum up number of items found, ignoring amount. * - ``TotalAmount`` - Sum up "amount" of each item. Optionally counting zero as one. ---- .. _doc_item_asset_blueprints_inputitem:amount: Amount :ref:`uint8 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::: Quantity of this item needed to craft the blueprint. Minimum value of one. ---- .. _doc_item_asset_blueprints_inputitem:allowempty: AllowEmpty :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, items with an "amount" of zero are included in eligible supplies. Otherwise, they are ignored (default). Defaults to ``true`` if ``CountEmptyAsOne`` is true. This option exists primarily for the ``FillTargetItem`` operation's internal use. ---- .. _doc_item_asset_blueprints_inputitem:allowfull: AllowFull :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, items with an "amount" greather than or equal to their maximum amount are ignored. Otherwise, they are eligible (default). This option exists primarily for the ``FillTargetItem`` operation's internal use. ---- .. _doc_item_asset_blueprints_inputitem:allowmaxquality: AllowMaxQuality :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, items with quality of 100% are eligible (default). Otherwise, they are ignored. This option exists primarily for the ``RepairTargetItem`` operation's internal use. ---- .. _doc_item_asset_blueprints_inputitem:countemptyasone: CountEmptyAsOne :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, items with an "amount" of zero are included in eligible supplies as amount 1. This option is used in vanilla for salvaging empty magazines. ---- .. _doc_item_asset_blueprints_inputitem:countingmethod: CountingMethod :ref:`ECraftingInputCountingMethod ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Determines how available amount of this input is calculated. Defaults to ``TotalItems`` unless ``Operation`` is ``FillTargetItem`` in which case ``TotalAmount`` is used. ---- .. _doc_item_asset_blueprints_inputitem:critical: Critical :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, the blueprint is hidden from the crafting menu if this input item is missing. Useful for blueprints that aren't relevant to the player without a specific item. For example, the first input item of a ``FillTargetItem`` blueprint is often marked ``Critical``. ---- .. _doc_item_asset_blueprints_inputitem:delete: Delete :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::: If true, this item is consumed when crafting the blueprint. If false, this item is marked as a "Tool" in the crafting menu. (For example, a Saw item required to cut wood.) ---- .. _doc_item_asset_blueprints_inputitem:id: ID :ref:`Asset Pointer ` to :ref:`Item Asset ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This property can also be set to a string value of ``this``, which will use the the owning asset's ID. Useful for Salvage blueprints to avoid accidentally writing the wrong ID. ---- .. _doc_item_asset_blueprints_inputitem:prioritization: Prioritization :ref:`ECraftingInputPrioritization ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls which items are used first. For example, whether to use the lowest quality items first. Defaults to ``LowestQuality`` unless ``Operation`` is ``FillTargetItem`` in which case ``LowestAmount`` is used. ================================================ FILE: items/blueprints_outputitem.rst ================================================ .. _doc_item_asset_blueprints_outputitem: Blueprint Output Items ====================== Configuration for a produced item in a :ref:`blueprint `. Value Format ------------ For straightforward cases, a simple one-liner format is supported: - {ID} - {ID} x {Amount} - this - this x {Amount} Examples: .. code-block:: unturneddat // Canned Beans: 78fefdd23def4ab6ac8301adfcc3b2d4 // Or, using Canned Beans' legacy ID: 13 // Two cans of beans: 13 x 2 // Owning asset: this // Two of owning asset: this x 2 Dictionary Format ----------------- Unlike the shorter format above, using these properties requires the ``{ }`` :ref:`dictionary ` format. For example: .. code-block:: unturneddat OutputItems [ { // First output item properties } { // Second output item properties } ] Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Amount ` - :ref:`uint8 ` - ``1`` * - :ref:`ID ` - :ref:`Asset Pointer ` to :ref:`Item ` - * - :ref:`Origin ` - :ref:`doc_data_eitemorigin` - ``Craft`` ---- .. _doc_item_asset_blueprints_outputitem:amount: Amount :ref:`uint8 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::: Quantity of this item created by the blueprint. Minimum value of one. ---- .. _doc_item_asset_blueprints_outputitem:id: ID :ref:`Asset Pointer ` to :ref:`Item Asset ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This property can also be set to a string value of ``this``, which will use the the owning asset's ID. Useful for blueprints creating the owning asset to avoid accidentally writing the wrong ID. ---- .. _doc_item_asset_blueprints_outputitem:origin: Origin :ref:`doc_data_eitemorigin` ``Craft`` :::::::::::::::::::::::::::::::::::::::::::: A kludge to override certain spawning properties. For example, setting the origin to ``Admin`` will cause items to spawn at full quality. ================================================ FILE: items/box-asset.rst ================================================ .. _doc_item_asset_box: Box Assets ========== Boxes are created from the ItemBoxAsset class. They are used to visualize certain information from the game's Steam Economy integration. Since this asset is not useful to modders, this documentation merely exists for completeness. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Box``) **ID** *uint16*: Must be a unique identifier. Box Asset Properties -------------------- **Generate** *int32*: The itemdefid granted by opening this box, which is used to display the correct UI element after an unbox. **Destroy** *int32*: The itemdefid removed by opening this box, which is used to display the correct UI element after an unbox. **Drops** *int32*: Corresponds to the total number of items in the box, so that the correct number of UI elements are displayed when showing box contents. **Drop_#** *int32*: The itemdefid of an item in the box, which is visually displayed as a UI element when showing box contents. **Item_Origin** *enum* (``Unbox``, ``Unwrap``): The localization key to use for for the unbox/unwrap menu button. **Probability_Model** *enum* (``Equalized``, ``Original``): UI elements regarding unbox probability chances are added depending on the specified enumerator. **Contains_Bonus_Items** *bool*: When true, adds a UI element regarding bonus items. ================================================ FILE: items/caliber-asset.rst ================================================ .. _doc_item_asset_caliber: Caliber Assets ============== The ItemCaliberAsset class is a base class that other classes are derived from. It is unusable on its own. Game Data File -------------- The ItemCaliberAsset class inherits properties from the :ref:`ItemAsset ` class. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Aiming_Movement_Speed_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Aiming_Recoil_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Aim_Duration_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Ballistic_Damage_Multiplier ` - :ref:`float32 ` - See description * - :ref:`Ballistic_Drop ` - :ref:`float32 ` - ``1`` * - :ref:`Calibers ` - :ref:`uint8 ` - ``0`` * - :ref:`Caliber_# ` - :ref:`uint16 ` - ``0`` * - :ref:`Damage ` - :ref:`float32 ` - *deprecated* * - :ref:`Destroy_Attachment_Colliders ` - :ref:`bool ` - ``true`` * - :ref:`Firerate ` - :ref:`uint8 ` - ``0`` * - :ref:`Instantiated_Attachment_Name_Override ` - :ref:`string ` - See description * - :ref:`Invulnerable ` - :ref:`bool ` - ``false`` * - :ref:`Paintable ` - :ref:`flag ` - * - :ref:`Recoil_X ` - :ref:`float32 ` - ``1`` * - :ref:`Recoil_Y ` - :ref:`float32 ` - ``1`` * - :ref:`Shake ` - :ref:`float32 ` - ``1`` * - :ref:`Spread ` - :ref:`float32 ` - ``1`` * - :ref:`Sway ` - :ref:`float32 ` - ``1`` Property Descriptions ````````````````````` .. _doc_item_asset_caliber:aiming_movement_speed_multiplier: Aiming_Movement_Speed_Multiplier :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on character movement speed while aiming down sights. ---- .. _doc_item_asset_caliber:aiming_recoil_multiplier: Aiming_Recoil_Multiplier :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on recoil magnitude while aiming down sights. ---- .. _doc_item_asset_caliber:aim_duration_multiplier: Aim_Duration_Multiplier :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the value of :ref:`Aim_In_Duration ` property available to the :ref:`ItemGunAsset ` class. ---- .. _doc_item_asset_caliber:ballistic_damage_multiplier: Ballistic_Damage_Multiplier :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on damage. Defaults to the value of the ``Damage`` property, or ``1`` if both properties are unset. ---- .. _doc_item_asset_caliber:ballistic_drop: Ballistic_Drop :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Gravity acceleration multiplier for bullets in flight. ---- .. _doc_item_asset_caliber:caliber_#: Caliber_# :ref:`uint16 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a caliber to check for attachment compatibility. This property is used in conjunction with ``Calibers``, which determines how many instances of this property should be read by the game. When this property is unset, it will default to ``0``. When the ``Magazine_Calibers`` property is not greater than ``0``, this property will default to the value of ``Caliber``. ---- .. _doc_item_asset_caliber:calibers: Calibers :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Set the length of the array containing the calibers for attachment compatibility. This property is used in conjunction with the ``Caliber_#`` property, and the value of ``Calibers`` should be equal to the number of instances of ``Caliber_#``. ---- .. _doc_item_asset_caliber:damage: Damage :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::: .. deprecated:: 3.27.0.0 Use ``Ballistic_Damage_Multiplier`` instead. Maintained for backwards compatibility. If both this property and ``Ballistic_Damage_Multiplier`` have been set, the latter's value is used. ---- .. _doc_item_asset_caliber:destroy_attachment_colliders: Destroy_Attachment_Colliders :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``false``, colliders are not destroyed when the attached ranged weapon's colliders are destroyed. This property exists for backwards compatibility with mods that may have relied on attachments having colliders, but using this property is not recommended. .. caution:: Mods with complex colliders on their custom attachments are frequently reported as causing low performance issues for players. It is recommended that your custom attachments do not rely on having colliders. ---- .. _doc_item_asset_caliber:firerate: Firerate :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::: The value of the attached ranged weapon's :ref:`Firerate ` property is reduced by the value of this property. A larger decrease will allow for the ranged weapon to fire more often. ---- .. _doc_item_asset_caliber:instantiated_attachment_name_override: Instantiated_Attachment_Name_Override :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Name to use when instantiating attachment prefab. By default, the value of ``GUID`` is used. Since Unity's built-in Animation component references GameObjects by name, this property can help share animations between items. For example, a magazine attachment with GUID ``dbfb1d0d11ca438e9dffb95f76e61274`` will instantiate Magazine.prefab as (Gun)/Magazine/dbfb1d0d11ca438e9dffb95f76e61274 by default. With ``Instantiated_Attachment_Name_Override`` set to "Example" it would instead spawn as (Gun)/Magazine/Example. ---- .. _doc_item_asset_caliber:invulnerable: Invulnerable :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, gun can damage entities with Invulnerable tag. ---- .. _doc_item_asset_caliber:paintable: Paintable :ref:`flag ` ::::::::::::::::::::::::::::::::::::: When this flag is included, the attachment should be affected by Steam Economy skins that include support for skinning attachments. ---- .. _doc_item_asset_caliber:recoil_x: Recoil_X :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on horizontal recoil. ---- .. _doc_item_asset_caliber:recoil_y: Recoil_Y :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on vertical recoil. ---- .. _doc_item_asset_caliber:shake: Shake :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on shake. ---- .. _doc_item_asset_caliber:spread: Spread :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on bullet spread. ---- .. _doc_item_asset_caliber:sway: Sway :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on scope sway. ================================================ FILE: items/charge-asset.rst ================================================ .. _doc_item_asset_charge: Charge Assets ============= Charges (or "remote explosives") are created from the ItemChargeAsset class. They can be placed and then remotely detonated with a :ref:`remote trigger `. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Charge``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Charge``) **ID** *uint16*: Must be a unique identifier. Charge Asset Properties ----------------------- **Animal_Damage** *float*: Damage dealt to animals caught within the area-of-effect explosion. **Barricade_Damage** *float*: Damage dealt to barricades caught within the area-of-effect explosion. **Explosion2** *uint16* or *GUID*: ID or GUID of effect to play upon detonation. **Explosion_Launch_Speed** *float*: Launch speed of players caught within the area-of-effect explosion, in meters per second. Defaults to the value of ``Player_Damage * 0.1``. **Object_Damage** *float*: Damage dealt to objects caught within the area-of-effect explosion. Defaults to the value of ``Resource_Damage``. **Player_Damage** *float*: Damage dealt to players caught within the area-of-effect explosion. **Resource_Damage** *float*: Damage dealt to resources caught within the area-of-effect explosion. **Structure_Damage** *float*: Damage dealt to structures caught within the area-of-effect explosion. **Vehicle_Damage** *float*: Damage dealt to vehicles caught within the area-of-effect explosion. **Range2** *float*: Radius of the damaging, area-of-effect explosion. **Zombie_Damage** *float*: Damage dealt to zombies caught within the area-of-effect explosion. ================================================ FILE: items/clothing-asset.rst ================================================ .. _doc_item_asset_clothing: Clothing Assets =============== The ItemClothingAsset class is a base class that other classes are derived from. It is unusable on its own. Items that use a class derived from this class are known as clothing items. Clothing can be worn by players and zombies, although they may function slightly differently between the two. Game Data File -------------- The ItemClothingAsset class inherits properties from the :ref:`ItemAsset ` class. Clothing items will always display a quality value. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Armor ` - :ref:`float32 ` - ``1`` * - :ref:`Armor_Explosion ` - :ref:`float32 ` - See description * - :ref:`Beard_Visible ` - :ref:`bool ` - ``true`` * - :ref:`Destroy_Clothing_Colliders ` - :ref:`bool ` - ``true`` * - :ref:`Falling_Damage_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Hair_Visible ` - :ref:`bool ` - ``true`` * - :ref:`Mirror_Left_Handed_Model ` - :ref:`bool ` - ``true`` * - :ref:`Movement_Speed_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Prevents_Falling_Broken_Bones ` - :ref:`bool ` - ``false`` * - :ref:`Priority_Over_Cosmetic ` - :ref:`bool ` - See description * - :ref:`Proof_Fire ` - :ref:`flag ` - * - :ref:`Proof_Radiation ` - :ref:`flag ` - * - :ref:`Proof_Water ` - :ref:`flag ` - * - :ref:`Skin_Override ` - :ref:`string ` - * - :ref:`Visible_On_Ragdoll ` - :ref:`bool ` - ``true`` * - :ref:`WearAudio ` - :ref:`Master Bundle Pointer ` - See description Property Descriptions ````````````````````` .. _doc_item_asset_clothing:armor: Armor :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on damage received to the covered body part(s). The affected body part(s) will differ depending on the child class. ---- .. _doc_item_asset_clothing:armor_explosion: Armor_Explosion :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the damage received from area-of-effect explosions. Defaults to the value of ``Armor``. ---- .. _doc_item_asset_clothing:beard_visible: Beard_Visible :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, the character's facial hair should be visible (unless disabled by some other condition). ---- .. _doc_item_asset_clothing:destroy_clothing_colliders: Destroy_Clothing_Colliders :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``false``, colliders are *not* destroyed when the clothing is attached to the player character. For example, equipped vanilla clothing do not have any colliders. But some mods (e.g., armor with a hitbox) may have relied on child colliders not being destroyed. ---- .. _doc_item_asset_clothing:falling_damage_multiplier: Falling_Damage_Multiplier :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on damage received from falling. ---- .. _doc_item_asset_clothing:hair_visible: Hair_Visible :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, the character's hair should be visible (unless disabled by some other condition). ---- .. _doc_item_asset_clothing:mirror_left_handed_model: Mirror_Left_Handed_Model :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Clothing should be mirrored when the player is using the left-handed setting. This property only affects 3D clothing items, being: vests, backpacks, masks, glasses, and hats. ---- .. _doc_item_asset_clothing:movement_speed_multiplier: Movement_Speed_Multiplier :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on movement speed. ---- .. _doc_item_asset_clothing:prevents_falling_broken_bones: Prevents_Falling_Broken_Bones :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, the player will never receive the Broken Bones debuff from falling. ---- .. _doc_item_asset_clothing:priority_over_cosmetic: Priority_Over_Cosmetic :ref:`bool ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This property can be set to override the default cosmetic override behavior. The default behavior will differ depending on the asset. For most assets, cosmetics are displayed over clothing. For glasses using the ``Vision`` property, the clothing item has priority over the cosmetic. .. note:: This only has an effect in PvP mode servers. ---- .. _doc_item_asset_clothing:proof_fire: Proof_Fire :ref:`flag ` :::::::::::::::::::::::::::::::::::::: When this flag is included, this clothing item is considered fireproof. When a fireproof shirt and fireproof pants are worn together, the player becomes immune to fire damage. This property has no effect on other clothing types. ---- .. _doc_item_asset_clothing:proof_radiation: Proof_Radiation :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::: When this flag is included, this clothing item is considered radiation-proof. When a radiation-proof mask is worn, the player will not be affected by standard deadzones. When radiation-proof pants, a radiation-proof shirt, and a radiation-proof mask are all worn together, the player will not be damaged by full-suit deadzones. This protection only lasts for as long as the radiation-proof mask's item quality is greater than 0%. The mask's quality will deplete over time while inside of a deadzone, but can be replenished with :ref:`radiation filters `. ---- .. _doc_item_asset_clothing:proof_water: Proof_Water :ref:`flag ` ::::::::::::::::::::::::::::::::::::::: When this flag is included, this clothing item is considered waterproof. When waterproof glasses are worn, the player's screen is no longer blurred when underwater. When waterproof glasses and a waterproof backpack are worn together, the player's oxygen will deplete at a greatly reduced rate while underwater. This property has no effect on other clothing types. ---- .. _doc_item_asset_clothing:skin_override: Skin_Override :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::::::::: Optional name of a renderer that should use the player's skin material. For example, the `Conflicting Conscience `_ cosmetic adds miniature versions of the player sitting on their shoulder. ---- .. _doc_item_asset_clothing:visible_on_ragdoll: Visible_On_Ragdoll :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, this clothing item should be visible on ragdolls. ---- .. _doc_item_asset_clothing:wear_audio: WearAudio :ref:`Master Bundle Pointer ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioClip or OneShotAudioDefinition to play upon equipping this clothing item. Default value is dependent on the child asset. Backpacks and vests will use ``Sounds/Zipper.mp3`` by default. Otherwise, ``Sounds/Sleeve.mp3`` is used. ================================================ FILE: items/cloud-asset.rst ================================================ .. _doc_item_asset_cloud: Cloud Assets ============ Clouds (or "parachutes") are created from the ItemCloudAsset class. They can affect a player's gravity when held. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Cloud``) **Useable** *enum* (``Cloud``) **ID** *uint16*: Must be a unique identifier. Cloud Asset Properties ---------------------- **Gravity** *float*: Multiplier on the influence of gravity. ================================================ FILE: items/consumeable-asset.rst ================================================ .. _doc_item_asset_consumeable: Consumeable Assets ================== Consumable items are irreversibly consumed by the player on use, and directly affect a player's stats such as food or health. This inherits the :ref:`WeaponAsset ` class. Consumeable Asset Properties ---------------------------- **Aid** *flag*: Specified if the item can be used on other players, via the "Secondary" action. **Bleeding** *flag*: Specified if the item should remove the "Bleeding" status effect. Deprecated in favor of Bleeding_Modifier. **Bleeding_Modifier** *enum* (``Cut``, ``Heal``, ``None``): Determines the effect the consumable has in relation to the "Bleeding" status effect. **Broken** *flag*: Specified if the item should remove the "Broken Bones" status effect. Deprecated in favor of Bones_Modifier. **Bones_Modifier** *enum* (``Break``, ``Heal``, ``None``): Determines the effect the consumable has in relation to the "Broken Bones" status effect. **ConsumeAudioClip** :ref:`Master Bundle Pointer `: AudioClip to play when the consumeable is used. **Disinfectant** *byte*: Amount of immunity restored. **Energy** *byte*: Amount of stamina restored. **Experience** *int*: Amount of experience added or removed. **Explosion** *uint16* or *GUID*: ID or GUID of the explosion effect to play upon consumption. **Food** *byte*: Amount of food restored. If the amount of food to restore is larger than the amount of water to restore, then food constrains water. **Health** *byte*: Amount of health restored. **Item_Reward_Spawn_ID** *uint16*: ID of the item spawn table to generate an item from upon consuming the consumable. The number of items generated is random, depending on the range defined by Min_Item_Rewards and Max_Item_Rewards. **Max_Item_Rewards** *int*: Maximum number of items that can be generated from the spawn table specified by Item_Reward_Spawn_ID. **Min_Item_Rewards** *int*: Minimum number of items that can be generated from the spawn table specified by Item_Reward_Spawn_ID. **Oxygen** *sbyte*: Amount of oxygen restored or depleted. **Randomize_Consume_Audio_Pitch** *bool*: If false, ``ConsumeAudioClip`` always plays with ``1.0`` pitch. Defaults to true. **Should_Delete_After_Use** *bool*: Boolean for if the item should be deleted after being consumed. Defaults to true. **Virus** *byte*: Amount of immunity depleted. **Vision** *uint*: Length of hallucinations, in seconds. The length does not stack when consuming multiple hallucinogenics. Instead, the timer is reset to the longer value. **Warmth** *uint*: Amount of warmth added. **Water** *byte*: Amount of water restored. If the amount of water to restore is less than the amount of food to restore, then water is constrained by food. Rewards ------- Consumables can use quest rewards. A common usage is to create consumables with multiple (but still limited) uses, by placing a new item in the player's inventory after consuming the original. Alternatively, consuming a consumable may be required to complete a quest. Refer to :ref:`Rewards ` documentation for additional documentation. These rewards are prefixed with ``Quest_``. For example, ``Quest_Rewards 1``. ================================================ FILE: items/detonator-asset.rst ================================================ .. _doc_item_asset_detonator: Detonator Assets ================ Detonators (or "remote triggers") are created from the ItemDetonatorAsset class. They can be used to detonate :ref:`remote explosives `. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Detonator``) **Useable** *enum* (``Detonator``) **ID** *uint16*: Must be a unique identifier. Detonator Asset Properties -------------------------- Remote triggers have no unique asset properties. Refer to :ref:`item asset documentation ` for additional properties. ================================================ FILE: items/farm-asset.rst ================================================ .. _doc_item_asset_farm: Farm Assets =========== Farms (or "plants") are created from the ItemFarmAsset class. They are placeable seeds capable of growing into harvestable crops. When a seed is planted, it will grow over time until eventually harvestable. Growing can be finished immediately by either rainfall, or by using a :ref:`growth supplement ` on the plant. A fully-grown crop can be harvested, which deals 2 damage to the crop. A crop can be harvested until it has 0 health remaining. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Farm``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Farm``) **ID** *uint16*: Must be a unique identifier. Farm Asset Properties --------------------- **Affected_By_Agriculture_Skill** *bool*: If true, the amount of crops acquired when harvesting the plant is affected by the `Agriculture skill `_. Defaults to true. **Allow_Fertilizer** *bool*: If true, allows the player to use fertilizer to fully grow the plant. Defaults to true. **Grow** *ushort*: Legacy ID of the item to spawn when harvested. **Grow_SpawnTable** :ref:`GUID `: GUID of a spawntable from which to spawn an item when harvested. **Growth** *uint*: In seconds, how long before the crop is fully grown. **Harvest_Reward_Experience** *uint*: The amount of experience gained upon harvesting. Defaults to 1. **Ignore_Soil_Restrictions** *bool*: If false, only allow placement on Soil Materials. If true, allow placement anywhere. Default to false. **Rain_Affects_Growth** *bool*: If true, the plant will fully finish growing after rainy weather. Defaults to true. **Harvest_Rewards**: NPC reward list granted when harvesting the grown plant. For more information, please refer to the :ref:`Rewards ` documentation. .. tip:: The ``Health`` property from the parent ItemAsset class can be configured to allow for harvesting a crop multiple times. A plant can be harvested a number of items equal to ``Health / 2``. For example, a plant with 10 health can be harvested up to 5 times. ================================================ FILE: items/filter-asset.rst ================================================ .. _doc_item_asset_filter: Filter Assets ============= Filters (or "radiation filters") are created from the ItemFilterAsset class. They can be used to replenish the quality of radiation-proof :ref:`masks `. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Filter``) **Useable** *enum* (``Filter``) **ID** *uint16*: Must be a unique identifier. Filter Asset Properties ----------------------- Radiation filters have no unique asset properties. Refer to parent classes for additional properties. ================================================ FILE: items/fisher-asset.rst ================================================ .. _doc_item_asset_fisher: Fisher Assets ============= Fishers (or "fishing poles") are created from the ItemFisherAsset class. They are useables that allow for catching fish. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Fisher``) **Useable** *enum* (``Fisher``) **ID** *uint16*: Must be a unique identifier. Fisher Asset Properties ----------------------- **Reward_Experience_Min** *int32*: Minimum amount (inclusive) of experience to grant upon successfully catching something. Defaults to 3. **Reward_Experience_Max** *int32*: Maximum amount (inclusive) of experience to grant upon successfully catching something. Defaults to 3. **Reward_ID** *uint16*: Legacy ID of the spawn table a reward should be generated from upon successfully catching something with the fishing pole. Fishing poles can use quest rewards. Refer to :ref:`Rewards ` documentation for additional documentation. These rewards are prefixed with ``Quest_``. For example, ``Quest_Rewards 1``. **Fish_Bite_Interval_Multiplier** *float*: Multiplier for interval before a fish takes the bait. Defaults to 1. **FishingRewardMode** *enum*: ``Rod`` or ``WaterVolumes``. Defaults to ``Rod`` for backwards compatibility. ``Rod``: Fishing rod itself defines rewards. Ignore per-volume rewards. ``WaterVolumes``: Use per-volume (or per-level if volume unspecified) rewards. If level doesn't support volume rewards, fallback to ``Rod`` rewards. .. seealso:: :ref:`Level Asset fishing properties `. **CatchChallenge_Enabled** *bool*: If true, player must complete a challenge when fish takes the bait before catching. Defaults to false for backwards compatibility. **CatchChallenge_CursorSize** *float*: Size of window item must be within to catch. Defaults to 0.2. **CatchChallenge_Gravity** *float*: Downward acceleration while input is not held. Defaults to 1. **CatchChallenge_Acceleration** *float*: Upward acceleration while input is held. Defaults to 1. **CatchChallenge_UpperRestitution** *float*: How much velocity to preserve when bouncing off the top. Defaults to 0.5 (50%). **CatchChallenge_LowerRestitution** *float*: How much velocity to preserve when bouncing off the bottom. Defaults to 0.5 (50%). **CatchChallenge_CaptureSpeed** *float*: Multiplier for how quickly item is caught while within cursor. Defaults to 1 (100%). **CatchChallenge_EscapeSpeed** *float*: Multiplier for how quickly the player loses while item is outside the cursor. Defaults to 1 (100%). ================================================ FILE: items/fishing-catchable-properties.rst ================================================ .. _doc_item_fishing_catchable_properties: Fishing Catchable Properties ============================ These options are specified in an item's :ref:`Fishing_Catchable` :ref:`Dictionary`. **Capture_Duration** *float*: How long the player must keep the item within the cursor before it's caught. Defaults to 2 seconds. **Escape_Duration** *float*: How long before the item gets away. Defaults to 2 seconds. **Spring_Stiffness** *float*: Scales acceleration toward target position (without exceeding limits). Defaults to 16. **Spring_Damping** *float*: Reduces speed toward target position. Defaults to 4. **Min_Relocate_Interval** *float*: Minimum seconds before target position changes. Defaults to 1.5 seconds. **Max_Relocate_Interval** *float*: Maximum seconds before target position changes. Defaults to 2 seconds. **Max_Upward_Acceleration** *float*: Upward acceleration cannot increase beyond this limit. Defaults to 1.5. **Max_Downward_Acceleration** *float*: Downward acceleration cannot increase beyond this limit. Defaults to 1.2. **Max_Upward_Speed** *float*: Upward speed cannot increase beyond this limit. Defaults to 0.6. **Max_Downward_Speed** *float*: Downward speed cannot increase beyond this limit. Defaults to 0.45. **Upper_Restitution** *float*: How much velocity to preserve when bouncing off the top. Defaults to 0.6 (60%). **Lower_Restitution** *float*: How much velocity to preserve when bouncing off the bottom. Defaults to 0.4 (40%). **Min_Target_Delta** *float*: When choosing a new position, it will be at least this far away. Defaults to 0.3 **Max_Target_Delta** *float*: When choosing a new position, it will be at most this far away. Defaults to 0.4. **Min_Target_Position** *float*: [0, 1] Minimum choosable position. Defaults to 0.1. **Max_Target_Position** *float*: [0, 1] Maximum choosable position. Defaults to 0.9. .. tip:: For example, the vanilla Lobster's configuration is: .. code-block:: unturneddat Fishing_Catchable { Min_Relocate_Interval 0.3 Max_Relocate_Interval 1 Max_Upward_Acceleration 1.3 Max_Downward_Acceleration 1.75 Max_Upward_Speed 0.5 Max_Downward_Speed 1.2 Upper_Restitution 0 Lower_Restitution 2 Min_Target_Delta 0.35 Max_Target_Delta 0.4 Min_Target_Position 0 Max_Target_Position 0.4 Capture_Duration 2.75 Escape_Duration 1.25 Spring_Stiffness 20 Spring_Damping 4 } ================================================ FILE: items/food-asset.rst ================================================ .. _doc_item_asset_food: Food Assets =========== Food items are created from the ItemFoodAsset class. They can be consumed by the player. This inherits the :ref:`ConsumeableAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Food``) **Useable** *enum* (``Consumeable``) **ID** *uint16*: Must be a unique identifier. Food Asset Properties --------------------- Food have no unique asset properties. Refer to parent classes for additional properties. ================================================ FILE: items/fuel-asset.rst ================================================ .. _doc_item_asset_fuel: Fuel Assets =========== Fuel items (or "fuel canisters") are created from the ItemFuelAsset class. They are useables able to siphon, store, and deposit fuel. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Fuel``) **Useable** *enum* (``Fuel``) **ID** *uint16*: Must be a unique identifier. Fuel Asset Properties --------------------- **Always_Spawn_Full** *bool*: If true, this item will always spawn filled at full capacity. **Delete_After_Filling_Target** *bool*: If true, this item is removed from the player's inventory after adding fuel to target. **Fuel** *uint16*: Maximum units of fuel that can be stored in the fuel canister. ================================================ FILE: items/gear-asset.rst ================================================ .. _doc_item_asset_gear: Gear Assets =========== The ItemGearAsset class is a base class that other classes are derived from. It is unusable on its own. Game Data File -------------- The ItemGearAsset class inherits properties from the :ref:`ItemClothingAsset ` class. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Beard ` - :ref:`flag ` - * - :ref:`Beard_Override ` - :ref:`string ` - * - :ref:`Beard_Override_NonGoldColor ` - :ref:`Color ` - * - :ref:`Hair ` - :ref:`flag ` - * - :ref:`Hair_Override ` - :ref:`string ` - * - :ref:`Hair_Override_NonGoldColor ` - :ref:`Color ` - Some inherited properties behave differently when used by this class. Notably, these are: #. | :ref:`Beard_Visible ` (from :ref:`ItemClothingAsset `). This property's default behavior is altered. Refer to this class's ``Beard`` property instead. #. | :ref:`Hair_Visible ` (from :ref:`ItemClothingAsset `). This property's default behavior is altered. Refer to this class's ``Hair`` property instead. Property Descriptions ````````````````````` .. _doc_item_asset_gear:beard: Beard :ref:`flag ` ::::::::::::::::::::::::::::::::: When this flag is not included, the parent class's :ref:`Beard_Visible ` property is set to false. This flag must be included if the character's facial hair should be visible. ---- .. _doc_item_asset_gear:beard_override: Beard_Override :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: When this property is set, the game will look for a child Mesh Renderer component in Unity that has the same name as this property's value. If a matching Mesh Renderer is found, its material will be changed to the character's hbeardair material. This property is used by certain cosmetics that entirely cover the character's beard, so that the player's selected beard color can still be used for customization. ---- .. _doc_item_asset_gear:beard_override_nongoldcolor: Beard_Override_NonGoldColor :ref:`Color ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: For items using BeardOverride, the beard material color will default to this for players without the Gold Upgrade. (Since the Gold Upgrade is required for full RGB control, the default beard colors may look boring for items that cover the beard but aren't beards in of themselves.) Also used as the color in the cosmetic preview. ---- .. _doc_item_asset_gear:hair: Hair :ref:`flag ` :::::::::::::::::::::::::::::::: When this flag is not included, the parent class's :ref:`Hair_Visible ` property is set to false. This flag must be included if the character's hair should be visible. ---- .. _doc_item_asset_gear:hair_override: Hair_Override :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::::::::: When this property is set, the game will look for a child Mesh Renderer component in Unity that has the same name as this property's value. If a matching Mesh Renderer is found, its material will be changed to the character's hair material. This property is used by certain cosmetics that entirely cover the character's hair, so that the player's selected hair color can still be used for customization. ---- .. _doc_item_asset_gear:hair_override_nongoldcolor: Hair_Override_NonGoldColor :ref:`Color ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: For items using hairOverride, the hair material color will default to this for players without the Gold Upgrade. (Since the Gold Upgrade is required for full RGB control, the default hair colors may look boring for items that cover the hair but aren't hair in of themselves.) Also used as the color in the cosmetic preview. ================================================ FILE: items/generator-asset.rst ================================================ .. _doc_item_asset_generator: Generator Assets ================ Generators are created from the ItemGeneratorAsset class. They are a placeable power sources. Players can deposit fuel into generators with a :ref:`fuel canister `. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Generator``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Generator``) **ID** *uint16*: Must be a unique identifier. Generator Asset Properties -------------------------- **Capacity** *uint16*: Maximum units of fuel that can be stored in the generator. Defaults to 0. **Wirerange** *float* [0, 256]: In meters, the radius around the generator that is provided electricity. **Burn** *float*: How many seconds it takes to burn one unit of fuel. ================================================ FILE: items/glasses-asset.rst ================================================ .. _doc_item_asset_glasses: Glasses Assets ============== Glasses are created from ItemGlassesAsset. They are clothing items that can be worn by players and zombies. This inherits the :ref:`GearAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Glasses``) **Useable** *enum* (``Clothing``) **ID** *uint16*: Must be a unique identifier. Glasses Asset Properties ------------------------ **Blindfold** *flag*: Specified if glasses should blacken the player's screen. **Nightvision_Allowed_In_ThirdPerson** *bool*: If ``true``, nightvision works in third-person, not just first-person. Defaults to ``false`` for backwards compatibility. Vanilla nightvision has this set to true. **Nightvision_Color** :ref:`color `: Overrides the default color when using ``Vision Military``. This property supports using legacy color parsing. **Nightvision_Fog_Intensity** *float32*: Intensity of fog while nightvision is active. **Vision** :ref:`doc_data_elightingvision`: Determines the type of lighting vision to use. When looking to assign a custom nightvision color via the ``Nightvision_Color`` property, you should use the ``Military`` enumerator. When the ``Headlamp`` enumerator is used, you can also specify properties from the :ref:`doc_data_playerspotlightconfig` struct. Defaults to ``None``. ================================================ FILE: items/grip-asset.rst ================================================ .. _doc_item_asset_grip: Grip Assets =========== Grips (or "grip attachments") are created from the ItemGripAsset class. They are inventory items that can be attached to ranged weapons. This inherits the :ref:`CaliberAsset ` class. Game Data File -------------- Grip attachments inherit properties from the CaliberAsset class, which in turn inherits properties from the ItemAsset class. Properties that are required to be included are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Grip`` Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Bipod ` - :ref:`flag ` - Property Descriptions ````````````````````` .. _doc_item_asset_grip:bipod: Bipod :ref:`flag ` ::::::::::::::::::::::::::::::::: Stat-changing properties should only take effect while prone. ================================================ FILE: items/grower-asset.rst ================================================ .. _doc_item_asset_grower: Grower Assets ============= Growers (or "growth supplements") are created from the ItemGrowerAsset class. They can be used to instantly finish growing a :ref:`plant `. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Grower``) **Useable** *enum* (``Grower``) **ID** *uint16*: Must be a unique identifier. Grower Asset Properties ----------------------- Growth supplements have no unique asset properties. Refer to :ref:`item asset documentation ` for additional properties. ================================================ FILE: items/gun-asset.rst ================================================ .. _doc_item_asset_gun: Gun Assets ========== The ItemGunAsset class is used for ranged weapons (or "guns"), which can be used by players to deal damage. Some examples of vanilla ranged weapons include the `Eaglefire `_ and `Crossbow `_. Unity Asset Bundle Contents --------------------------- .. figure:: /img/UnityExampleGun.png An example of a gun being set up in the Unity editor. To get started, either follow the steps to begin creating a custom item from the :ref:`introduction `, or duplicate the contents of a prepackaged example asset. Item (Prefab) ````````````` Open the "Item" Prefab, and add six child GameObjects named "Barrel", "Grip", "Sight", "Tactical", "Magazine", and "Eject". Most custom guns will want to have these six child GameObjects, although they are not strictly required. The "Barrel", "Grip", "Sight", "Tactical", and "Magazine" GameObjects will determine the location of attachments on your gun. The "Sight" GameObject also determines where the camera will be positioned when aiming down sights. Shells are emitted from the "Eject" GameObject. If an "View" GameObject is added, the camera will use its position when aiming down sights if a sight attachment has not been attached to the gun. When a gun can accept more than one type of magazine caliber, it may be desirable to have the position of the magazine attachment depend on its caliber ID. Add a child to the "Magazine" GameObject, named "Caliber_#". For example, adding "Caliber_1" would cause magazine attachments using caliber ID 1 to use that position instead of the "Magazine" GameObject's position. (This is supported for the other attachment types as well.) Additional Setup for Bows ::::::::::::::::::::::::: .. figure:: /img/UnityExampleCrossbow.png An example of a crossbow being set up in the Unity editor. Bows require additional GameObjects to simulate the drawing of the bowstring. Note that bowstrings are only simulated from the first-person perspective. Add a new child GameObject named "Rope", and set its state to inactive. The "Rope" GameObject should include a Line Renderer component. Vanilla bowstrings use a custom Material named "Rope" with the Unlit-Rope Shader, but this is not required. Add two child GameObjects named "Left" and "Right". These GameObjects will determine the end points of the bowstring. If a third GameObject named "Rest" is included, it will be used as the middle point of the bowstring when aiming down sights. Including a fourth GameObject named "Nock" will allow the bow to be fired without aiming down sights. Additionally, the "Rest" GameObject will act as a middle point when not aiming down sights, and the "Nock" GameObject will act as a middle point while aiming down sights. Additional Setup for Economy Items :::::::::::::::::::::::::::::::::: There are several child GameObjects that can be added related to skins. Custom items are ineligible to receive skins, so there is usually no reason to add these to the Prefab. If an item has an "Icon2" GameObject included, its position and orientation will be used when generating icons of skins on this item. A GameObject named "Stat_Tracker" determines the location where stat trackers will appear on the gun, while a GameObject named "Effect" will determine the position of mythical effects on the gun. Animations (Prefab) ``````````````````` In addition to animations used by any equippable item, guns have an additional set of animations that they can use. Adding animations named "Aim_Start" and "Aim_Stop" will cause an animation to be played whenever the player starts or stops aiming down sights. Animations named "Attach_Start" and "Attach_Stop" will play when an attachment is attached or unattached to the gun. The "Sprint_Start" and "Sprint_Stop" animations play when the player starts and stops sprinting. The "Reload" animation is played when reloading the gun. The "Hammer" animation is played under certain conditions where it would make sense to manually eject a cartridge from the gun. For example: after reloading an gun that had an empty magazine, or after firing a single-shot weapon (such as a bolt-action rifle or pump-action shotgun). If a gun is configured to use the gun jamming feature, the "UnjamChamber" animation will play when a jam occurs. Audio Clips ``````````` In addition to the Audio Clips that can be included for equippable items, guns have an additional set of audio clips they can use. If an Audio Clip named "Shoot" is included, it will play after the gun is fired. Including Audio Clips named "Reload" and "Hammer" will cause audio to play after reloading and hammering the gun, respectively. An "Aim" Audio Clip can be included to have audio play after aiming down sights. For example, a longbow might want to have an the sound of the bow being drawn play. Miniguns can also include an Audio Clip named "Minigun" to have audio play while revving the minigun. If a gun is configured to use the gun jamming feature, the "ChamberJammed" Audio Clip will play when a jam occurs. Game Data File -------------- Ranged weapons inherit properties from the :ref:`ItemWeaponAsset ` class. Any properties from parent classes that are required—or highly recommended—are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Slot ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Gun`` * - :ref:`ItemAsset ` - :ref:`Useable ` - ``Gun`` * - :ref:`ItemWeaponAsset ` - :ref:`Range ` - Additionally, all ranged weapons require that the ``Action`` property has been configured. Note that ranged weapons will always show a quality value. Properties `````````` Ranged weapons have a significant number of properties. To make navigating these easier, they have been categorized into one of several property tables. Many of these tables contain similar properties that are often used together. .. list-table:: Uncategorized :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Aim_In_Duration ` - :ref:`float32 ` - ``0.2`` * - :ref:`Aiming_Movement_Speed_Multiplier ` - :ref:`float32 ` - See description * - :ref:`Alert_Radius ` - :ref:`float32 ` - ``48`` * - :ref:`Can_Aim_During_Sprint ` - :ref:`bool ` - ``false`` * - :ref:`Gunshot_Rolloff_Distance ` - :ref:`float32 ` - See description * - :ref:`Must_Aim_To_Shoot ` - :ref:`bool ` - See description * - :ref:`Range_Rangefinder ` - :ref:`float32 ` - See description * - :ref:`Scale_Aim_Animation_Speed ` - :ref:`bool ` - ``true`` * - :ref:`Stop_Aiming_After_Shooting ` - :ref:`bool ` - ``false`` * - :ref:`DriverTurretViewmodelMode ` - :ref:`EDriverTurretViewmodelMode ` - ``OffscreenWhileAiming`` .. list-table:: Calibers :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Attachment_Caliber_# ` - :ref:`uint16 ` - See description * - :ref:`Attachment_Calibers ` - :ref:`int32 ` - See description * - :ref:`Caliber ` - :ref:`uint16 ` - ``0`` * - :ref:`Magazine_Caliber_# ` - :ref:`uint16 ` - See description * - :ref:`Magazine_Calibers ` - :ref:`int32 ` - See description * - :ref:`Requires_NonZero_Attachment_Caliber ` - :ref:`bool ` - ``false`` .. list-table:: Damage :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Damage_Falloff_Max_Range ` - :ref:`float32 ` - ``1`` * - :ref:`Damage_Falloff_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Damage_Falloff_Range ` - :ref:`float32 ` - ``1`` * - :ref:`Instakill_Headshots ` - :ref:`bool ` - ``false`` .. list-table:: Effects :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Explosion ` - :ref:`doc_data_guid` or :ref:`uint16 ` - ``0`` * - :ref:`Muzzle ` - :ref:`doc_data_guid` or :ref:`uint16 ` - ``0`` * - :ref:`Shell ` - :ref:`doc_data_guid` or :ref:`uint16 ` - See description .. list-table:: Firing Mechanism :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Action ` - :ref:`EAction ` - * - :ref:`Auto ` - :ref:`flag ` - * - :ref:`Bursts ` - :ref:`int32 ` - ``0`` * - :ref:`Fire_Delay_Seconds ` - :ref:`int32 ` - ``0`` * - :ref:`Firerate ` - :ref:`uint8 ` - ``0`` * - :ref:`Safety ` - :ref:`flag ` - * - :ref:`Semi ` - :ref:`flag ` - .. list-table:: Hook Attachments :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Barrel ` - :ref:`uint16 ` - ``0`` * - :ref:`Grip ` - :ref:`uint16 ` - ``0`` * - :ref:`Sight ` - :ref:`uint16 ` - ``0`` * - :ref:`Tactical ` - :ref:`uint16 ` - ``0`` * - :ref:`Hook_Barrel ` - :ref:`flag ` - * - :ref:`Hook_Grip ` - :ref:`flag ` - * - :ref:`Hook_Sight ` - :ref:`flag ` - * - :ref:`Hook_Tactical ` - :ref:`flag ` - .. list-table:: Jamming :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Can_Ever_Jam ` - :ref:`flag ` - * - :ref:`Jam_Quality_Threshold ` - :ref:`float32 ` - ``0.4`` * - :ref:`Jam_Max_Chance ` - :ref:`float32 ` - ``0.1`` * - :ref:`Unjam_Chamber_Anim ` - :ref:`string ` - ``UnjamChamber`` .. list-table:: Magazine Attachments :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Allow_Magazine_Change ` - :ref:`bool ` - ``true`` * - :ref:`Ammo_Max ` - :ref:`uint8 ` - ``0`` * - :ref:`Ammo_Min ` - :ref:`uint8 ` - ``0`` * - :ref:`Ammo_Per_Shot ` - :ref:`uint8 ` - ``1`` * - :ref:`Delete_Empty_Magazines ` - :ref:`flag ` - *deprecated* * - :ref:`Hammer_Time ` - :ref:`float32 ` - ``1`` * - :ref:`Infinite_Ammo ` - :ref:`bool ` - ``false`` * - :ref:`Magazine ` - :ref:`uint16 ` - ``0`` * - :ref:`Magazine_Replacement_#_ID ` - :ref:`uint16 ` - ``0`` * - :ref:`Magazine_Replacement_#_Map ` - :ref:`string ` - * - :ref:`Magazine_Replacements ` - :ref:`int32 ` - ``0`` * - :ref:`Reload_Time ` - :ref:`float32 ` - ``1`` * - :ref:`Replace ` - :ref:`float32 ` - ``1`` * - :ref:`Should_Delete_Empty_Magazines ` - :ref:`bool ` - See description * - :ref:`Unplace ` - :ref:`float32 ` - ``0`` .. list-table:: Projectiles (Ballistic System) :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Ballistic_Drop ` - :ref:`float32 ` - *deprecated* * - :ref:`Ballistic_Steps ` - :ref:`uint8 ` - See description * - :ref:`Ballistic_Travel ` - :ref:`float32 ` - See description * - :ref:`Bullet_Gravity_Multiplier ` - :ref:`float32 ` - ``4`` .. list-table:: Projectiles (Physics System) :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Ballistic_Force ` - :ref:`float32 ` - ``0.002`` * - :ref:`Projectile_Explosion_Launch_Speed ` - :ref:`float32 ` - See description * - :ref:`Projectile_Lifespan ` - :ref:`float32 ` - ``30`` * - :ref:`Projectile_Penetrate_Buildables ` - :ref:`flag ` - .. list-table:: Rechambering Properties :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`CasingEjectCountAfterRechamberingAfterShooting ` - :ref:`int32 ` - ``1`` * - :ref:`CasingEjectCountAfterReload ` - :ref:`int32 ` - See description * - :ref:`EjectAfterHammerDelay ` - :ref:`float32 ` - ``0.45`` * - :ref:`EjectAfterReloadDelay ` - :ref:`float32 ` - ``0.5`` * - :ref:`EjectCasingAfterShooting ` - :ref:`bool ` - See description * - :ref:`RechamberAfterMagazineAttached ` - :ref:`ERechamberGunAfterReloadMode ` - ``IfAmmoWasEmpty`` * - :ref:`RechamberAfterMagazineDetached ` - :ref:`ERechamberGunAfterReloadMode ` - ``Always`` * - :ref:`RechamberAfterShotCount ` - :ref:`int32 ` - See description * - :ref:`RechamberAfterShotDelay ` - :ref:`float32 ` - ``0.25`` .. list-table:: Recoil :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Aiming_Recoil_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Recoil_Crouch ` - :ref:`float32 ` - ``0.85`` * - :ref:`Recoil_Max_X ` - :ref:`float32 ` - ``0`` * - :ref:`Recoil_Max_Y ` - :ref:`float32 ` - ``0`` * - :ref:`Recoil_Min_X ` - :ref:`float32 ` - ``0`` * - :ref:`Recoil_Min_Y ` - :ref:`float32 ` - ``0`` * - :ref:`Recoil_Midair ` - :ref:`float32 ` - ``1.0`` * - :ref:`Recoil_Prone ` - :ref:`float32 ` - ``0.7`` * - :ref:`Recoil_Sprint ` - :ref:`float32 ` - ``1.25`` * - :ref:`Recoil_Swimming ` - :ref:`float32 ` - ``1.1`` * - :ref:`Recover_X ` - :ref:`float32 ` - ``0`` * - :ref:`Recover_Y ` - :ref:`float32 ` - ``0`` .. list-table:: Shake :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Shake_Max_X ` - :ref:`float32 ` - ``0`` * - :ref:`Shake_Min_X ` - :ref:`float32 ` - ``0`` * - :ref:`Shake_Max_Y ` - :ref:`float32 ` - ``0`` * - :ref:`Shake_Min_Y ` - :ref:`float32 ` - ``0`` * - :ref:`Shake_Max_Z ` - :ref:`float32 ` - ``0`` * - :ref:`Shake_Min_Z ` - :ref:`float32 ` - ``0`` .. list-table:: Spread :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Spread_Aim ` - :ref:`float32 ` - ``0`` * - :ref:`Spread_Angle_Degrees ` - :ref:`float32 ` - ``0`` * - :ref:`Spread_Crouch ` - :ref:`float32 ` - ``0.85`` * - :ref:`Spread_Hip ` - :ref:`float32 ` - *deprecated* * - :ref:`Spread_Midair ` - :ref:`float32 ` - ``1.5`` * - :ref:`Spread_Prone ` - :ref:`float32 ` - ``0.7`` * - :ref:`Spread_Sprint ` - :ref:`float32 ` - ``1.25`` * - :ref:`Spread_Swimming ` - :ref:`float32 ` - ``1.1`` .. _doc_item_asset_gun:eaction: EAction Enumeration ``````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``Trigger`` - Corresponds to the "Trigger" action. Uses the ballistic projectile system. * - ``Bolt`` - Corresponds to the "Bolt" action. Uses the ballistic projectile system. * - ``Pump`` - Corresponds to the "Pump" action. Uses the ballistic projectile system. * - ``Rail`` - Corresponds to the "Rail" action. Uses the ballistic projectile system. * - ``String`` - Corresponds to the "String" action. Uses the ballistic projectile system. * - ``Break`` - Corresponds to the "Break" action. Uses the ballistic projectile system. * - ``Rocket`` - Corresponds to the "Rocket" action. Uses the physics projectile system. * - ``Minigun`` - Corresponds to the "Minigun" action. Uses the ballistic projectile system. .. _doc_item_asset_gun:edriverturretviewmodelmode: EDriverTurretViewmodelMode Enumeration `````````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``OffscreenWhileAiming`` - Default. Pushes first-person arms off-screen while aiming. Originally implemented for the Fighter Jet where it looks weird if your arms are still visible when the camera zooms in while "aiming." * - ``AlwaysOffscreen`` - Push first-person arms off-screen when equipped. * - ``AlwaysOnscreen`` - Included for completeness. .. _doc_item_asset_gun:erechambergunafterreloadmode: ERechamberGunAfterReloadMode Enumeration ```````````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``IfAmmoWasEmpty`` - Default. Plays "Hammer" animation if ammo count was zero. * - ``Never`` - Regardless of ammo, does not play "Hammer" animation after reloading. * - ``Always`` - Regardless of ammo, will play "Hammer" animation after reloading. Property Descriptions ````````````````````` .. _doc_item_asset_gun:action: Action :ref:`EAction ` :::::::::::::::::::::::::::::::::::::::::::::::::: The value of this property determines how the weapon functions when used, including whether it uses *ballistic projectiles*, or *physics projectiles*. Different properties are available to the weapon depending on the value of this property. Although most action mechanisms utilize ballistic projectiles, the ``Rocket`` action mechanism uses physics projectiles instead. Additionally, any projectiles from these weapons (e.g., the `Rocket Launcher `_) are explosive. To fire a weapon with the ``String`` action mechanism, a player must be aiming down sights – unless a "Nock" GameObject has been added during its Unity setup. ---- .. _doc_item_asset_gun:aim_in_duration: Aim_In_Duration :ref:`float32 ` ``0.2`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How long it takes to fully aim down sights, in seconds. ---- .. _doc_item_asset_gun:aiming_movement_speed_multiplier: Aiming_Movement_Speed_Multiplier :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the player's movement speed while aiming down sights. Defaults to ``0.75`` when ``Can_Aim_During_Sprint`` is ``false``. Otherwise, defaults to ``1``. ---- .. _doc_item_asset_gun:aiming_recoil_multiplier: Aiming_Recoil_Multiplier :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on recoil magnitude while aiming down sights. ---- .. _doc_item_asset_gun:alert_radius: Alert_Radius :ref:`float32 ` ``48`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The radius of the alert generated by ranged weapons when they are fired. Zombies or animals caught within this radius are alerted. This radius is measured in meters. ---- .. _doc_item_asset_gun:allow_magazine_change: Allow_Magazine_Change :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``false``, the magazine cannot be removed, replaced, or reloaded. This functions similar to a few other properties, such as ``Hook_Barrel`` or ``Hook_Grip`` when determing valid hook attachment slots. ---- .. _doc_item_asset_gun:ammo_max: Ammo_Max :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum amount of ammo to randomly generate in the magazine attachment that was attached to the weapon by default. ---- .. _doc_item_asset_gun:ammo_min: Ammo_Min :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum amount of ammo to randomly generate in the magazine attachment that was attached to the weapon by default. ---- .. _doc_item_asset_gun:ammo_per_shot: Ammo_Per_Shot :ref:`uint8 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Number of ammunition consumed per shot. For example, a value of ``3`` would consume three ammo every time the weapon is fired, while a value of ``0`` would allow for the weapon to have infinite ammo. ---- .. _doc_item_asset_gun:attachment_caliber_#: Attachment_Caliber_# :ref:`uint16 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a caliber to check for hook attachment compatibility. This property is used in conjunction with ``Attachment_Calibers``, which determines how many instances of this property should be read by the game. When this property is unset, it will default to ``0``. When the ``Attachment_Calibers`` property is not greater than ``0``, this property will default to the value of any ``Magazine_Caliber_#`` properties. For example, a valid configuration for a ranged weapon's calibers could be: .. code-block:: unturnedasset Attachment_Calibers 2 Attachment_Caliber_0 1 Attachment_Caliber_1 9 Magazine_Calibers 3 Magazine_Caliber_0 1 Magazine_Caliber_1 4 Magazine_Caliber_2 9 This would allow the ranged weapon to use hook attachments with caliber IDs of 1 or 9, and to use magazine attachments with caliber IDs of 1, 4, or 9. ---- .. _doc_item_asset_gun:attachment_calibers: Attachment_Calibers :ref:`int32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Set the length of the array containing the calibers for hook attachment compatibility. This property is used in conjunction with the ``Attachment_Caliber_#`` property, and the value of ``Attachment_Calibers`` should be equal to the number of instances of ``Attachment_Caliber_#``. When this property is not greater than ``0`` – it will default to the value of ``Magazine_Calibers``, and the ``Attachment_Caliber_#`` property can no longer be customized. To use this property, ``Magazine_Calibers`` must be configured. ---- .. _doc_item_asset_gun:auto: Auto :ref:`flag ` :::::::::::::::::::::::::::::::: The weapon has an automatic firing mode. ---- .. _doc_item_asset_gun:ballistic_drop: Ballistic_Drop :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: .. deprecated:: 3.23.7.0 Use ``Bullet_Gravity_Multiplier`` instead. Existing values are automatically converted if ``Bullet_Gravity_Multiplier`` has not been configured. Running the game with the ``-LogBallisticDropConversion`` :ref:`launch option ` will log the equivalent ``Bullet_Gravity_Multiplier`` value. ---- .. _doc_item_asset_gun:ballistic_force: Ballistic_Force :ref:`float32 ` ``0.002`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The amount of force that should be applied to the *physics projectile*, measured in Newtons. It may be helpful to read Unity's `Rigidbody.AddForce documentation `_ to better understand physics projectiles. Properties used by physics projectiles (such as ``Ballistic_Force``) cannot be used alongside properties intended for ballistic projectiles (such as ``Ballistic_Travel`` or ``Bullet_Gravity_Multiplier``). ---- .. _doc_item_asset_gun:ballistic_steps: Ballistic_Steps :ref:`uint8 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Lifespan of *ballistic projectiles*. A higher value relative to ``Ballistic_Travel`` will result in less muzzle velocity. Must be a value greater than ``0``. Defaults to ``Range ÷ Ballistic_Travel``, rounded up to the nearest integer. To avoid a mismatch between the weapon's max range and its manual ballistic range, it is recommend to only configure ``Ballistic_Steps`` or ``Ballistic_Travel`` (or neither) – no both. ---- .. _doc_item_asset_gun:ballistic_travel: Ballistic_Travel :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Travel speed of *ballistic projectiles*. A higher value relative to ``Ballistic_Steps`` will result in more muzzle velocity. Must be a value greater than ``0.1``. Defaults to ``10``. If ``Ballistic_Steps`` is specified and greater than ``0``, and ``Ballistic_Travel`` is not specified, then ``Ballistic_Travel`` defaults to ``Range ÷ Ballistic_Steps``. To avoid a mismatch between the weapon's max range and its manual ballistic range, it is recommend to only configure ``Ballistic_Travel`` or ``Ballistic_Steps`` (or neither) – no both. ---- .. _doc_item_asset_gun:barrel: Barrel :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a barrel attachment that should be attached by default. The ``Hook_Barrel`` flag is not required to use this property. ---- .. _doc_item_asset_gun:bullet_gravity_multiplier: Bullet_Gravity_Multiplier :ref:`float32 ` ``4`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier for gravity's acceleration. This property is available to *ballistic projectile* weapons. Setting this value to ``1`` allows for more realistic bullet drop. .. note:: This defaults to ``4`` because *Unturned*'s maximum engagement distance is rather short, but this distance may be raised in the future if/when network improvements are made to the game. Gravity defaults to 9.81 m/s², or can be configured in the :ref:`doc_mapping_config`. ---- .. _doc_item_asset_gun:bursts: Bursts :ref:`int32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::: When a value greater than ``0`` is provided, the weapon has a burst firing mode. A number of shots equal to this value is fired when using this mode. ---- .. _doc_item_asset_gun:caliber: Caliber :ref:`uint16 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of the caliber to check for hook attachment and magazine attachment compatibility. To add compatibility for multiple calibers, or to configure hook attachment and magazine attachment compatibility separately, use the ``Magazine_Calibers`` and ``Attachment_Calibers`` properties instead. ---- .. _doc_item_asset_gun:can_aim_during_sprint: Can_Aim_During_Sprint :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, the player can sprint while aiming down sights. ---- .. _doc_item_asset_gun:can_ever_jam: Can_Ever_Jam :ref:`flag ` :::::::::::::::::::::::::::::::::::::::: When this flag is included, the weapon can jam. Weapons have a chance of jamming once their quality drops below a certain threshold. Starting from the initial threshold, the chance of jamming on each shot is blended between between 0% and a specified max chance. The "ChamberJammed" Audio Clip is played when a jam occurs, as well as the animation "UnjamChamber" if present. For an example, refer to ``.../Guns/Cobra_Jam/Cobra_Jam.dat`` in the game files. ---- .. _doc_item_asset_gun:casingejectcountafterrechamberingaftershooting: CasingEjectCountAfterRechamberingAfterShooting :ref:`int32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Only applicable if :ref:`RechamberAfterShotCount ` is non-zero. If greater than zero, emit this many bullet casing particles after :ref:`EjectAfterHammerDelay ` seconds pass. ---- .. _doc_item_asset_gun:casingejectcountafterreload: CasingEjectCountAfterReload :ref:`int32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If greater than zero, emit this many bullet casing particles after :ref:`EjectAfterReloadDelay ` seconds pass. Defaults to :ref:`Ammo_Max ` for ``Break`` Action guns. Zero otherwise. ---- .. _doc_item_asset_gun:ejectcasingaftershooting: EjectCasingAfterShooting :ref:`bool ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, emit a bullet casing particle when a shot is fired. Defaults to true for ``Trigger`` and ``Minigun`` action guns. ---- .. _doc_item_asset_gun:damage_falloff_max_range: Damage_Falloff_Max_Range :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Percentage of maximum range where damage stops decreasing. For example, a max falloff range value of ``0.6`` with a range of ``200`` means damage stops dropping off after 120 meters. ---- .. _doc_item_asset_gun:damage_falloff_multiplier: Damage_Falloff_Multiplier :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Percentage of damage to apply at maximum range. For example, a falloff multiplier value of ``0.25`` with a damage value of ``40`` means 10 damage will be dealt at maximum range. ---- .. _doc_item_asset_gun:damage_falloff_range: Damage_Falloff_Range :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Percentage of maximum range where damage begins decreasing. For example, a falloff range value of ``0.3`` with a range value of ``200`` means damage begins dropping off after 60 meters. ---- .. _doc_item_asset_gun:delete_empty_magazines: Delete_Empty_Magazines :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::::::: .. deprecated:: 3.30.3.0 Use ``Should_Delete_Empty_Magazines`` instead. When this flag is included, the attached magazine attachment is deleted when fully depleted. ---- .. _doc_item_asset_gun:ejectafterhammerdelay: EjectAfterHammerDelay :ref:`float32 ` ``0.45`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How long in seconds after hammering to eject a bullet casing. Only applicable if :ref:`RechamberAfterShotCount ` is non-zero. ---- .. _doc_item_asset_gun:ejectafterreloaddelay: EjectAfterReloadDelay :ref:`float32 ` ``0.5`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How long in seconds after reloading to eject bullet casings. Only applicable if :ref:`CasingEjectCountAfterReload ` is greater than zero. ---- .. _doc_item_asset_gun:explosion: Explosion :ref:`doc_data_guid` or :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of the effect that should be used for explosions caused by ``Action Rocket`` projectiles. ---- .. _doc_item_asset_gun:fire_delay_seconds: Fire_Delay_Seconds :ref:`int32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Delay before the weapon is actually fired, in seconds. ---- .. _doc_item_asset_gun:firerate: Firerate :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::: The value of this property affects the minimum number of ticks between the firing of consecutive shots. A higher ``Firerate`` value will cause the weapon to have a slower rate of a fire. The weapon's rate of fire can be calculated with ``50 ÷ (Firerate + 1)``, as the rounds per second. ---- .. _doc_item_asset_gun:grip: Grip :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a grip attachment that should be attached by default. The ``Hook_Grip`` flag is not required to use this property. ---- .. _doc_item_asset_gun:gunshot_rolloff_distance: Gunshot_Rolloff_Distance :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Distance over which the gunshot audio rolls off until it is completely inaudible, in meters. Defaults to ``16`` when using ``Action String``; defaults to ``64`` when using ``Action Rocket``; otherwise, defaults to ``512``. ---- .. _doc_item_asset_gun:hammer_time: Hammer_Time :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the time it takes to pull back the hammer a ranged weapon after firing. This does not affect the actual animation speed, but the cooldown before the player can perform other actions (such as shooting) again. Values less than ``1`` have no effect. ---- .. _doc_item_asset_gun:hook_barrel: Hook_Barrel :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::::: When this flag is included, the ranged weapon has a barrel attachment slot. ---- .. _doc_item_asset_gun:hook_grip: Hook_Grip :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::: When this flag is included, the ranged weapon has a grip attachment slot. ---- .. _doc_item_asset_gun:hook_sight: Hook_Sight :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::::::: When this flag is included, the ranged weapon has a sight attachment slot. ---- .. _doc_item_asset_gun:hook_tactical: Hook_Tactical :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::::::: When this flag is included, the ranged weapon has a tactical attachment slot. ---- .. _doc_item_asset_gun:infinite_ammo: Infinite_Ammo :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When ``true``, ammunition is not depleted from the magazine attachment. This allows for the weapon to have infinite ammo, so long as a magazine attachment with a number of rounds remaining equal to ``Ammo_Per_Shot`` is attached. ---- .. _doc_item_asset_gun:instakill_headshots: Instakill_Headshots :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, a player that is headshot with this weapon is instantly killed. This does not affect zombies, unless the world's difficulty configuration has the ``Weapons_Use_Player_Damage`` setting enabled. ---- .. _doc_item_asset_gun:jam_max_chance: Jam_Max_Chance :ref:`float32 ` ``0.1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Decimal-to-percent chance for jamming to occur. This property requires ``Can_Ever_Jam``. ---- .. _doc_item_asset_gun:jam_quality_threshold: Jam_Quality_Threshold :ref:`float32 ` ``0.4`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The maximum threshold for when jamming can occur. This value is a decimal-to-percent representation of the item's quality value. For example, a threshold of ``0.4`` allows jamming to start occuring at 40% item quality. This property requires ``Can_Ever_Jam``. ---- .. _doc_item_asset_gun:magazine: Magazine :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a magazine attachment that should be attached by default. ---- .. _doc_item_asset_gun:magazine_caliber_#: Magazine_Caliber_# :ref:`uint16 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a caliber to check for magazine attachment compatibility. This property is used in conjunction with ``Magazine_Calibers``, which determines how many instances of this property should be read by the game. When this property is unset, it will default to ``0``. When the ``Magazine_Calibers`` property is not greater than ``0``, this property will default to the value of ``Caliber``. ---- .. _doc_item_asset_gun:magazine_calibers: Magazine_Calibers :ref:`int32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: Set the length of the array containing the calibers for magazine attachment compatibility. This property is used in conjunction with the ``Magazine_Caliber_#`` property, and the value of ``Magazine_Calibers`` should be equal to the number of instances of ``Magazine_Caliber_#``. When this property is not greater than ``0`` – it will default to ``1``, and the ``Magazine_Caliber_#`` property can no longer be customized. This property is often used alongside ``Attachment_Calibers``, but this is optional. ---- .. _doc_item_asset_gun:magazine_replacement_#_id: Magazine_Replacement_#_ID :ref:`uint16 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a magazine attachment that should be used as an alternative default when certain condition(s) are met. This property is used in conjunction with ``Magazine_Replacements``, which determines how many instances of this property should be read by the game. ---- .. _doc_item_asset_gun:magazine_replacement_#_map: Magazine_Replacement_#_Map :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This value should be the name of a map. When the weapon spawns on this map, this condition has been met. This property requires ``Magazine_Replacement_#_ID``. ---- .. _doc_item_asset_gun:magazine_replacements: Magazine_Replacements :ref:`int ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ``Magazine_Replacements`` and its related properties are used to add alternative magazine attachments that should be used as the weapon's default when certain condition(s) are met. This value sets the length of the array containing any alternative default magazine attachments. This property is used in conjunction with the ``Magazine_Replacement_#_ID`` property, and the value of ``Magazine_Replacements`` should be equal to the number of instances of ``Magazine_Replacement_#_ID``. ---- .. _doc_item_asset_gun:must_aim_to_shoot: Must_Aim_To_Shoot :ref:`bool ` :::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, the gun cannot shoot unless the player is aiming. Defaults to true for ``Minigun`` :ref:`doc_item_asset_gun:action`. False otherwise. ``String`` :ref:`doc_item_asset_gun:action` overrides ``Must_Aim_To_Shoot`` functionality. ---- .. _doc_item_asset_gun:muzzle: Muzzle :ref:`doc_data_guid` or :ref:`uint16 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of the effect to play after shooting. This is emitted from the ranged weapon's "Barrel" GameObject. ---- .. _doc_item_asset_gun:projectile_explosion_launch_speed: Projectile_Explosion_Launch_Speed :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Players caught within the area-of-effect explosion caused by a *physics projectile* weapon are launched at this speed. For example, this can be used to create velocity-related items like "rocket-jumping" mods. Defaults to ``Player_Damage × 0.1``. ---- .. _doc_item_asset_gun:projectile_lifespan: Projectile_Lifespan :ref:`float32 ` ``30`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Lifespan of *physics projectiles*, in seconds. After this much time elapses, the projectile despawns. ---- .. _doc_item_asset_gun:projectile_penetrate_buildables: Projectile_Penetrate_Buildables :ref:`flag ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The area-of-effect explosions caused by *physics projectiles* penetrate through buildables when this flag is set. ---- .. _doc_item_asset_gun:range_rangefinder: Range_Rangefinder :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Overrides the maximum distance displayed when using a "Rangefinder" tactical attachment on this weapon. For example, it may be useful to set this property when using ``Action Rocket``, as explosive projectiles use ``Range`` to determine the explosion radius rather than the maximum range of the weapon. Defaults to the value of the ``Range`` property. ---- .. _doc_item_asset_gun:rechamberaftermagazineattached: RechamberAfterMagazineAttached :ref:`ERechamberGunAfterReloadMode ` ``IfAmmoWasEmpty`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Determines whether "Hammer" animation plays after attaching a magazine. This happens when a magazine replaces another OR fills previously empty slot. ---- .. _doc_item_asset_gun:rechamberaftermagazinedetached: RechamberAfterMagazineDetached :ref:`ERechamberGunAfterReloadMode ` ``Always`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Determines whether "Hammer" animation plays after detached a magazine. This happens when a magazine is removed from the gun without a replacement. ---- .. _doc_item_asset_gun:rechamberaftershotcount: RechamberAfterShotCount :ref:`int32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If non-zero, hammer animation plays after shooting after shooting this many shots and :ref:`RechamberAfterShotDelay `: seconds pass. Shot count resets after reloading, hammering, or dequipping the gun. Defaults to ``1`` for ``Bolt`` and ``Pump`` Action guns. Zero otherwise. ---- .. _doc_item_asset_gun:rechamberaftershotdelay: RechamberAfterShotDelay :ref:`float32 ` ``0.25`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: How long in seconds after firing to rechamber the gun by playing the Hammer animation. Only applicable if :ref:`RechamberAfterShotCount ` is non-zero. ---- .. _doc_item_asset_gun:recoil_crouch: Recoil_Crouch :ref:`float32 ` ``0.85`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on camera recoil while crouched. ---- .. _doc_item_asset_gun:recoil_max_x: Recoil_Max_X :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum horizontal camera recoil in degrees. This property is used in conjunction with ``Recoil_Min_Y``. ---- .. _doc_item_asset_gun:recoil_max_y: Recoil_Max_Y :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum vertical camera recoil in degrees. This property is used in conjunction with ``Recoil_Min_X``. ---- .. _doc_item_asset_gun:recoil_min_x: Recoil_Min_X :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum horizontal camera recoil in degrees. This property is used in conjunction with ``Recoil_Max_X``. ---- .. _doc_item_asset_gun:recoil_min_y: Recoil_Min_Y :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum vertical camera recoil in degrees. This property is used in conjunction with ``Recoil_Max_Y``. ---- .. _doc_item_asset_gun:recoil_midair: Recoil_Midair :ref:`float32 ` ``1.0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on camera recoil while jumping and/or falling. ---- .. _doc_item_asset_gun:recoil_prone: Recoil_Prone :ref:`float32 ` ``0.7`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on camera recoil while prone. ---- .. _doc_item_asset_gun:recoil_sprint: Recoil_Sprint :ref:`float32 ` ``1.25`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on camera recoil while sprinting. This property is not relevant unless ``Can_Aim_During_Sprint`` has been set to ``true``. ---- .. _doc_item_asset_gun:recoil_swimming: Recoil_Swimming :ref:`float32 ` ``1.1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on camera recoil while swimming. ---- .. _doc_item_asset_gun:recover_x: Recover_X :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on camera degrees to be counter-animated horizontally over the next 250 milliseconds. ---- .. _doc_item_asset_gun:recover_y: Recover_Y :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on camera degrees to be counter-animated vertically over the next 250 milliseconds. ---- .. _doc_item_asset_gun:reload_time: Reload_Time :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on time it takes to finish reloading the ranged weapon. This does not affect the actual animation speed, but the cooldown before the player can perform other actions (such as shooting) again. Values less than ``1`` have no effect. ---- .. _doc_item_asset_gun:replace: Replace :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier of the reload animation length before the magazine is respawned. This does not affect the actual animation speed, but the cooldown before the player can perform other actions (such as shooting) again. Values less than ``0.01`` have no effect. ---- .. _doc_item_asset_gun:requires_nonzero_attachment_caliber: Requires_NonZero_Attachment_Caliber :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, attachments must specify at least one non-zero (``0``) caliber ID to be compatible. For example, this can be used to make most vanilla attachments (like the Tactical Laser, Dot Sight, and Vertical Grip) incompatible with this weapon. ---- .. _doc_item_asset_gun:safety: Safety :ref:`flag ` :::::::::::::::::::::::::::::::::: The weapon has a safety firing mode. ---- .. _doc_item_asset_gun:scale_aim_animation_speed: Scale_Aim_Animation_Speed :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When true, the length of the "Aim_Start" and "Aim_Stop" animations are scaled to match ``Aim_In_Duration`` (with modifiers). ---- .. _doc_item_asset_gun:semi: Semi :ref:`flag ` :::::::::::::::::::::::::::::::: The weapon has a semi-automatic firing mode. ---- .. _doc_item_asset_gun:shake_max_x: Shake_Max_X :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum 𝘟-axis model shake caused from firing the weapon. ---- .. _doc_item_asset_gun:shake_min_x: Shake_Min_X :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum 𝘟-axis model shake caused from firing the weapon. ---- .. _doc_item_asset_gun:shake_max_y: Shake_Max_Y :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum 𝘠-axis model shake caused from firing the weapon. ---- .. _doc_item_asset_gun:shake_min_y: Shake_Min_Y :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum 𝘠-axis model shake caused from firing the weapon. ---- .. _doc_item_asset_gun:shake_max_z: Shake_Max_Z :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum 𝘡-axis model shake caused from firing the weapon. ---- .. _doc_item_asset_gun:shake_min_z: Shake_Min_Z :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum 𝘡-axis model shake caused from firing the weapon. ---- .. _doc_item_asset_gun:shell: Shell :ref:`doc_data_guid` or :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of the effect to play after shooting, emitted from the ranged weapon's "Eject" GameObject. Defaults to ``33`` when using either ``Action Pump`` or ``Action Break``; defaults to ``1`` when using any other ``Action`` key-value pair except for ``Action Rail``; otherwise, defaults to ``0``. ---- .. _doc_item_asset_gun:should_delete_empty_magazines: Should_Delete_Empty_Magazines :ref:`bool ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Overrides how empty magazines are handled by the action item mode. When set to ``true``, empty magazine attachments are deleted when completely emptied. The default behavior depends on the configuration of the ``Action`` property. Defaults to ``true`` when using one of the following ``Action`` enumerators: ``Break``, ``Pump``, ``Rail``, ``Rocket``, or ``String``. Otherwise, defaults to ``false``. ---- .. _doc_item_asset_gun:sight: Sight :ref:`uint16 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a sight attachment that should be attached by default. The ``Hook_Sight`` flag is not required to use this property. ---- .. _doc_item_asset_gun:spread_aim: Spread_Aim :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the bullet spread while aiming down sights. This is multiplied by the ``Spread_Angle_Degrees`` value. ---- .. _doc_item_asset_gun:spread_angle_degrees: Spread_Angle_Degrees :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Bullet angle of deviation away from the aiming direction. For example, ``15`` means the shot could hit up to 15 degrees away from the center of the crosshair, whereas ``0`` will always hit the center of the crosshair. All other spread values are multipliers for this. ---- .. _doc_item_asset_gun:spread_crouch: Spread_Crouch :ref:`float32 ` ``0.85`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the bullet spread while crouched. ---- .. _doc_item_asset_gun:spread_hip: Spread_Hip :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::: .. deprecated:: 3.22.20.0 Use ``Spread_Angle_Degrees`` instead. Maintained for backwards compatibility. Running the game with the ``-LogGunSpreadConversion`` :ref:`launch option ` will log the equivalent ``Spread_Angle_Degrees`` value. ---- .. _doc_item_asset_gun:spread_midair: Spread_Midair :ref:`float32 ` ``1.5`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the bullet spread while jumping and/or falling. ---- .. _doc_item_asset_gun:spread_prone: Spread_Prone :ref:`float32 ` ``0.7`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the bullet spread while prone. ---- .. _doc_item_asset_gun:spread_sprint: Spread_Sprint :ref:`float32 ` ``1.25`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the bullet spread while sprinting. ---- .. _doc_item_asset_gun:spread_swimming: Spread_Swimming :ref:`float32 ` ``1.1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the bullet spread while swimming. ---- .. _doc_item_asset_gun:stop_aiming_after_shooting: Stop_Aiming_After_Shooting :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, the gun will stop aiming regardless of player input. ---- .. _doc_item_asset_gun:tactical: Tactical :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Legacy ID of a tactical attachment that should be attached by default. The ``Hook_Tactical`` flag is not required to use this property. ---- .. _doc_item_asset_gun:turret: Turret :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::: This weapon should be treated as a vehicular turret. This flag affects the player's first-person viewmodel while the weapon is held. ---- .. _doc_item_asset_gun:driverturretviewmodelmode: DriverTurretViewmodelMode :ref:`EDriverTurretViewmodelMode ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls how first-person arms are moved for turrets operated from the driver's seat. ---- .. _doc_item_asset_gun:unjam_chamber_anim: Unjam_Chamber_Anim :ref:`string ` ``UnjamChamber`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Name of an animation clip to play when unjamming the weapon. This property requires ``Can_Ever_Jam``. ---- .. _doc_item_asset_gun:unplace: Unplace :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier of the reload animation length before the magazine is despawned. This does not affect the actual animation speed, but the cooldown before the player can perform other actions (such as shooting) again. NPC Rewards ----------- Gun assets can use quest rewards. For example, every time the ranged weapon is fired an item could be spawned in the player's inventory. Alternatively, shooting the ranged weapon may be required to complete a quest. For more information, refer to the :ref:`Rewards ` documentation. These rewards are prefixed with ``Shoot_Quest_``. For example, ``Shoot_Quest_Rewards 1``. Understanding Projectile Systems -------------------------------- All ranged weapons utilize one of two projectile systems: the *ballistic projectile system*, or the *physics projectile system*. This is determined based on the :ref:`Action ` the weapon has been configured to use, although most weapons use the ballistic projectile system. Ballistic projectiles use a deterministic simulation. Their travel time, bullet drop, and other characteristics can be configured with properties such as :ref:`Ballistic_Travel ` and :ref:`Bullet_Gravity_Multiplier `. When the ballistics game mechanic is disabled, these weapons function as hitscan instead. Physics projectiles use Unity's physics simulation. Unlike ballistic projectiles, these are not deterministic. Additionally, physics projectiles cause area-of-effect explosions upon impact. The characteristics of physics projectiles can be configured with properties such as :ref:`Ballistic_Force ` and :ref:`Projectile_Explosion_Launch_Speed `. ================================================ FILE: items/hat-asset.rst ================================================ .. _doc_item_asset_hat: Hat Assets ========== The ItemHatAsset class is used by clothing items occupying the "hat" slot. Hats can be worn by players and zombies, and cover their head. Game Data File -------------- The ItemHatAsset class inherits properties from the :ref:`ItemGearAsset ` class. Properties that are required (or recommended) are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Hat`` * - :ref:`ItemAsset ` - :ref:`Useable ` - ``Clothing`` Properties `````````` Hats have no unique properties. Refer to parent classes for additional properties instead. ================================================ FILE: items/introduction.rst ================================================ .. _doc_item_asset_intro: Introduction to Items ===================== Items are created from the ItemAsset class. They encompass anything that can be carried in a player's in-game inventory. All items will share certain properties, but each item type may have its own unique properties as well. Please refer to :ref:`Asset Definitions ` and :ref:`Asset Bundles ` for the full documentation regarding assets and asset bundles. Unity Asset Bundle Contents --------------------------- .. figure:: /img/UnityExampleItem.png An example of an item being set up in the Unity editor. To get started, create a new folder for your custom item. The name of this folder will be relevant when further configuring your item after it has been exported from Unity. Item (Prefab) ````````````` Inside this folder, create a new Prefab named "Item". This should be tagged as 4: Item, and layered as 13: Item. Open the "Item" Prefab. Items can have multiple colliders including different types, but just attaching a Box Collider component to the root GameObject will usually suffice. It is recommended to use a minimum dimension of (0.2, 0.2, 0.2), because the large colliders are less likely to fall through a thin surface in a single physics tick. If your item only has one LOD, you can attach Mesh Filter and Mesh Renderer components directly to the root GameObject. Configure these components as desired. It is recommended to have multiple LODs for your item, so that less needs to be rendered when the item is far away. If your item should have multiple LODs, attach a LOD Group component to the root GameObject. Create a child GameObject for each LOD, named "Model_#" (e.g., "Model_0", "Model_1"). Attach the Mesh Filter and Mesh Renderer components to each one. Configure these components as desired. Add a new child GameObject named "Icon" to the root GameObject. This will be used to draw an icon with an orthographic camera. By default, the game will automatically calculate the position and size of the camera – so the only thing that needs to be configured is its orientation. To test the orientation of your icon, temporarily attach a Camera component with its Projection property set to "Orthographic". When satisified, delete the Camera component. Animations (Prefab) ``````````````````` For equippable items, a Prefab named "Animations" is required. The Prefab and the animations included can either be created from scratch, or they can be duplicated from the provided Unity packages. If you have installed the ExampleAssets.unitypackage we provide, you can find the vanilla animations for most item types in the game. Prefabs can be found along the ``CoreMasterBundle/Items`` path, while the raw animation files can be found along ``Game/Sources/Animations``. To create the Prefab from scratch instead, add a new Prefab named "Animations" in your custom item's folder. Add an Animation component to the root GameObject of the "Animations" Prefab. Every equippable item should have an animation named "Equip". If your weapon should be inspectable, it should also have an "Inspect" animation. Equip (Audio Clip) `````````````````` To have a sound play when the item is equipped, include an Audio Clip named "Equip" in your custom item's folder. Skin Base Textures `````````````````` .. note:: We should eventually add more documentation about this, but items support texture masking. This is rarely relevant for modders creating their own items, but it is important for skins. Items can optionally include ``Albedo_Base.png``, ``Metallic_Base.png``, or ``Emission_Base.png`` textures in their asset-bundled files. When using certain skins, those parts will be masked out and retain their original material. Game Data File -------------- The ``GUID``, ``Type``, and ``ID`` properties are required by all item assets. Most item assets will *usually* want (or need) to include the ``Rarity``, ``Useable``, ``Slot``, ``Size_X``, and ``Size_Y`` properties as well, with only a few excepions. Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Add_Default_Actions ` - :ref:`bool ` - See description * - :ref:`Allow_Manual_Drop ` - :ref:`bool ` - ``true`` * - :ref:`Amount ` - :ref:`uint8 ` - ``1`` * - :ref:`Backward ` - :ref:`flag ` - *deprecated* * - :ref:`Bypass_Hash_Verification ` - :ref:`bool ` - ``false`` * - :ref:`Bypass_ID_Limit ` - :ref:`flag ` - * - :ref:`Can_Player_Equip ` - :ref:`bool ` - See description * - :ref:`Can_Use_Underwater ` - :ref:`bool ` - See description * - :ref:`Count_Max ` - :ref:`uint8 ` - ``1`` * - :ref:`Count_Min ` - :ref:`uint8 ` - ``1`` * - :ref:`Deleted_At_Zero_Quality_Effect ` - :ref:`doc_assets_effect` - ``0`` * - :ref:`Deleted_At_Zero_Quality_Rewards ` - :ref:`doc_npc_asset_rewards` - ``0`` * - :ref:`Destroy_Item_Colliders ` - :ref:`bool ` - ``true`` * - :ref:`Equipable_Movement_Speed_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`EquipableModelParent ` - :ref:`EEquipableModelParent ` - See description * - :ref:`EquipablePrefab ` - :ref:`Master Bundle Pointer ` - * - :ref:`EquipAudioClip ` - :ref:`Master Bundle Pointer ` - ``Equip`` * - :ref:`Fishing_Catchable ` - :ref:`FishingCatchableProperties ` - * - :ref:`GUID ` - :ref:`doc_data_guid` - * - :ref:`ID ` - :ref:`uint16 ` - ``0`` * - :ref:`Ignore_TexRW ` - :ref:`flag ` - * - :ref:`InspectAudioDef ` - :ref:`Master Bundle Pointer ` - * - :ref:`Instantiated_Item_Name_Override ` - :ref:`string ` - See description * - :ref:`InventoryAudio ` - :ref:`Master Bundle Pointer ` - See description * - :ref:`Left_Handed_Characters_Mirror_Equipable ` - :ref:`bool ` - ``true`` * - :ref:`Override_Show_Quality ` - :ref:`bool ` - ``false`` * - :ref:`Pro ` - :ref:`flag ` - * - :ref:`Procedurally_Animate_Inertia ` - :ref:`bool ` - ``true`` * - :ref:`Quality_Max ` - :ref:`uint8 ` - ``90`` * - :ref:`Quality_Min ` - :ref:`uint8 ` - ``10`` * - :ref:`Rarity ` - :ref:`doc_data_eitemrarity` - ``Common`` * - :ref:`Shared_Skin_Lookup_ID ` - :ref:`uint16 ` - See description * - :ref:`Shared_Skin_Apply_Visuals ` - :ref:`bool ` - ``true`` * - :ref:`Should_Delete_At_Zero_Quality ` - :ref:`bool ` - ``false`` * - :ref:`Should_Drop_On_Death ` - :ref:`bool ` - ``true`` * - :ref:`Size_X ` - :ref:`uint8 ` - ``1`` * - :ref:`Size_Y ` - :ref:`uint8 ` - ``1`` * - :ref:`Size_Z ` - :ref:`float32 ` - ``-1`` * - :ref:`Size2_Z ` - :ref:`float32 ` - ``-1`` * - :ref:`Slot ` - :ref:`doc_data_eslottype` - ``None`` * - :ref:`Type ` - :ref:`doc_data_eitemtype` - * - :ref:`Use_Auto_Icon_Measurements ` - :ref:`bool ` - ``true`` * - :ref:`Use_Auto_Stat_Descriptions ` - :ref:`bool ` - ``true`` * - :ref:`Useable ` - :ref:`EUseableType ` - ``None`` .. _doc_item_asset_intro:eequipablemodelparent: EEquipableModelParent Enumeration ````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``RightHook`` - Item is attached to Right_Hook. * - ``LeftHook`` - Item is attached to Left_Hook. * - ``Spine`` - Item is attached to Spine. * - ``SpineHook`` - Item is attached to Spine_Hook, an optional extra child bone of the Spine bone. .. _doc_item_asset_intro:euseabletype: EUseableType Enumeration ```````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``None`` - Does not correspond to any useable type. * - ``Clothing`` - Corresponds to the "Clothing" useable type. * - ``Gun`` - Corresponds to the "Gun" useable type. * - ``Consumeable`` - Corresponds to the "Consumeable" useable type. * - ``Melee`` - Corresponds to the "Melee" useable type. * - ``Fuel`` - Corresponds to the "Fuel" useable type. * - ``Carjack`` - Corresponds to the "Carjack" useable type. * - ``Barricade`` - Corresponds to the "Barricade" useable type. * - ``Structure`` - Corresponds to the "Structure" useable type. * - ``Throwable`` - Corresponds to the "Throwable" useable type. * - ``Grower`` - Corresponds to the "Grower" useable type. * - ``Optic`` - Corresponds to the "Optic" useable type. * - ``Refill`` - Corresponds to the "Refill" useable type. * - ``Fisher`` - Corresponds to the "Fisher" useable type. * - ``Cloud`` - Corresponds to the "Cloud" useable type. * - ``Arrest_Start`` - Corresponds to the "Arrest_Start" useable type. * - ``Arrest_End`` - Corresponds to the "Arrest_End" useable type. * - ``Detonator`` - Corresponds to the "Detonator" useable type. * - ``Filter`` - Corresponds to the "Filter" useable type. * - ``Carlockpick`` - Corresponds to the "Carlockpick" useable type. Property Descriptions ````````````````````` .. _doc_item_asset_intro:add_default_actions: Add_Default_Actions :ref:`bool ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, actions are automatically created for refill ammo, repair, and salvage blueprints. Defaults to true if no ``Actions`` are specified. ---- .. _doc_item_asset_intro:allow_manual_drop: Allow_Manual_Drop :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Item can be manually dropped by the player. ---- .. _doc_item_asset_intro:amount: Amount :ref:`uint8 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::: Maximum capacity for container-like items, such as ammunition boxes. Typically used with ``Count_Min`` and ``Count_Max``. ---- .. _doc_item_asset_intro:bypass_hash_verification: Bypass_Hash_Verification :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Disable hash verification check, and allow for mismatched files. ---- .. _doc_item_asset_intro:bypass_id_limit: Bypass_ID_Limit :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::: Allows for using an ``ID`` value within the range reserved for official content. ---- .. _doc_item_asset_intro:can_player_equip: Can_Player_Equip :ref:`bool ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls whether or not this item can be equipped by the player. This property *technically* requires that ``Useable`` has been configured to any value other than ``None``, as items are not equippable without the functionality provided by having a Useable class. While the inclusion of this property may seem unorthodox, it does have some niche uses. For example, you could create a gun that can only be used by sentries. This property defaults to ``true`` if the ``Useable`` property has been set. Otherwise, this defaults to ``false``. ---- .. _doc_item_asset_intro:can_use_underwater: Can_Use_Underwater :ref:`bool ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: Item can be used while underwater. If the ``Slot`` property has *not* been set to ``Primary``, then this defaults to ``true``. Otherwise, this defaults to ``false``. ---- .. _doc_item_asset_intro:count_max: Count_Min :ref:`uint8 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum amount to generate, for container-like items. Typically used with ``Count_Max`` and ``Amount``. ---- .. _doc_item_asset_intro:count_min: Count_Max :ref:`uint8 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum amount to generate, for container-like items. Typically used with ``Count_Min`` and ``Amount``. ---- .. _doc_item_asset_intro:deleted_at_zero_quality_effect: Deleted_At_Zero_Quality_Effect :ref:`doc_data_assetptr` to :ref:`doc_assets_effect` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If assigned, and :ref:`Should_Delete_At_Zero_Quality ` is ``true``, this effect is played when the item breaks. ---- .. _doc_item_asset_intro:deleted_at_zero_quality_rewards: Deleted_At_Zero_Quality_Rewards :ref:`doc_npc_asset_rewards` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If assigned, and :ref:`Should_Delete_At_Zero_Quality ` is ``true``, these rewards are granted to the player when the item breaks. ---- .. _doc_item_asset_intro:destroy_item_colliders: Destroy_Item_Colliders :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``false``, colliders are not destroyed when the "Item" Prefab is attached to the character. For example equipped vanilla guns do not have any colliders, but some mods (e.g., riot shields) may have relied on child colliders not being destroyed. ---- .. _doc_item_asset_intro:equipable_movement_speed_multiplier: Equipable_Movement_Speed_Multiplier :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplies character movement speed while equipped in the player's hands. If a gun is equipped, then any gun attachment multipliers are combined as well. ---- .. _doc_item_asset_intro:equipablemodelparent: EquipableModelParent :ref:`EEquipableModelParent ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Overrides which transform to attach the item to when equipped by the player. Spine may be a better interpolation space for items with animations moving the model between hands. Normally, this property defaults to ``RightHook``. However, items using the deprecated ``Backward`` flag will cause this to instead use ``LeftHook``. ---- .. _doc_item_asset_intro:equipableprefab: EquipablePrefab :ref:`Master Bundle Pointer ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Overrides the model spawned when this item is equipped. For example, the "Equipable" Prefab could use an animated skinned mesh component while the regular "Item" Prefab only needs a static mesh component. ---- .. _doc_item_asset_intro:equipaudioclip: EquipAudioClip :ref:`Master Bundle Pointer ` ``Equip`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioClip to play when equipping. ---- .. _doc_item_asset_intro:fishing_catchable: Fishing_Catchable :ref:`Fishing Catchable Properties ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Overrides settings when caught by a fishing rod. For more information, please refer to :ref:`Fishing Catchable Properties `. ---- .. _doc_item_asset_intro:guid: GUID :ref:`doc_data_guid` ::::::::::::::::::::::::: Refer to :ref:`GUID ` documentation. Item assets are required to have this property. .. tip:: If the GUID property has been omitted from the asset file, then the game will automatically attempt to assign a random (and unique) GUID during a successful load. ---- .. _doc_item_asset_intro:id: ID :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::: Must be a unique identifier. Item assets are required to have this property. ---- .. _doc_item_asset_intro:ignore_texrw: Ignore_TexRW :ref:`flag ` :::::::::::::::::::::::::::::::::::::::: Read/writeable texture errors regarding this asset should be hidden from the error logs. ---- .. _doc_item_asset_intro:inspectaudiodef: InspectAudioDef :ref:`Master Bundle Pointer ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioClip or OneShotAudioDefinition to play when item is inspected. ---- .. _doc_item_asset_intro:instantiated_item_name_override: Instantiated_Item_Name_Override :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Name to use when instantiating "Item" Prefab. By default, the value of ``ID`` is used. Since Unity's built-in Animation component references GameObjects by name, this property can help share animations between items. ---- .. _doc_item_asset_intro:inventoryaudio: InventoryAudio :ref:`Master Bundle Pointer ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: AudioClip or OneShotAudioDefinition to play when item is picked up, moved within the inventory, and dropped. Default value is dependent on the child asset. ---- .. _doc_item_asset_intro:left_handed_characters_mirror_equipable: Left_Handed_Characters_Mirror_Equipable :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``false``, the equipped item model is mirrored to counteract the mirrored character. ---- .. _doc_item_asset_intro:override_show_quality: Override_Show_Quality :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Override to forcefully show item quality. ---- .. _doc_item_asset_intro:pro: Pro :ref:`flag ` ::::::::::::::::::::::::::::::: This is a Steam Economy item. ---- .. _doc_item_asset_intro:procedurally_animate_inertia: Procedurally_Animate_Inertia :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Whether viewmodel should accumulate angular velocity from animations. Useful for low-quality older animations, but should probably be disabled for high-quality newer animations. ---- .. _doc_item_asset_intro:quality_max: Quality_Max :ref:`uint8 ` ``90`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Maximum quality to generate. Typically used with ``Quality_Min``. ---- .. _doc_item_asset_intro:quality_min: Quality_Min :ref:`uint8 ` ``10`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Minimum quality to generate. Typically used with ``Quality_Max``. ---- .. _doc_item_asset_intro:rarity: Rarity :ref:`doc_data_eitemrarity` ``Common`` ::::::::::::::::::::::::::::::::::::::::::::: Rarity of the item, as text shown in menus and colors used for highlights. ---- .. _doc_item_asset_intro:shared_skin_lookup_id: Shared_Skin_Lookup_ID :ref:`uint16 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Share skins with another item. Defaults to item's ``ID``. ---- .. _doc_item_asset_intro:shared_skin_apply_visuals: Shared_Skin_Apply_Visuals :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If false, skin material and mesh are not applied when ``Shared_Skin_Lookup_ID`` is set. For example, a custom axe can transfer the kill counter and ragdoll effect from a vanilla item's skin without also transferring the material and mesh. ---- .. _doc_item_asset_intro:should_delete_at_zero_quality: Should_Delete_At_Zero_Quality :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Item should be deleted when at 0% quality. ---- .. _doc_item_asset_intro:should_drop_on_death: Should_Drop_On_Death :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When a player dies with this item, should an item drop be spawned? .. note:: The item is not kept after respawning. ---- .. _doc_item_asset_intro:size_x: Size_X :ref:`uint8 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::: In slots, the total width of the inventory space (i.e., the number of columns). ---- .. _doc_item_asset_intro:size_y: Size_Y :ref:`uint8 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::: In slots, the total height of the inventory space (i.e., the number of rows). ---- .. _doc_item_asset_intro:size_z: Size_Z :ref:`float32 ` ``-1`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Manually specify orthogonal camera size for item icons. This directly corresponds to the value of a Camera component's Size property in Unity. ---- .. _doc_item_asset_intro:size2_z: Size2_Z :ref:`float32 ` ``-1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Orthogonal camera size for economy icons. ---- .. _doc_item_asset_intro:slot: Slot :ref:`doc_data_eslottype` ``None`` ::::::::::::::::::::::::::::::::::::::: Which equipped item slot an item is valid to be equippable in. This is only relevant if your property has configured the ``Useable`` property. - ``None`` restricts the useable item to hotkeys. - ``Primary`` restricts the useable item to the primary slot. - ``Secondary`` restricts the useable item to the primary or secondary slots. - ``Tertiary`` is not implemented by this asset. - ``Any`` has no restrictions on slots or hotkeying. ---- .. _doc_item_asset_intro:type: Type :ref:`doc_data_eitemtype` :::::::::::::::::::::::::::::: Designates the item's class. Item assets are required to have this property. ---- .. _doc_item_asset_intro:use_auto_icon_measurements: Use_Auto_Icon_Measurements :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Automatically calculate axis-aligned item icon camera size from bounds. ---- .. _doc_item_asset_intro:use_auto_stat_descriptions: Use_Auto_Stat_Descriptions :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, properties like damage, storage, health, etc. are appended to the description. ---- .. _doc_item_asset_intro:useable: Useable :ref:`doc_item_asset_intro:euseabletype` ``None`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Setting this property adds functionality from a corresponding Useable class. Unless ``Can_Player_Equip`` has been configured otherwise, this *at least* means the item is equippable. This property is often used in conjunction with the ``Slot`` property, which determines where an item can be equipped from. Blueprints and Actions `````````````````````` In addition to the properties already described, item assets can utilize properties for :ref:`crafting blueprints ` and :ref:`context menu actions `. Localization ------------ **Name** *string*: Item name in user interfaces. **Description** :ref:`doc_data_richtext`: Item description in user interfaces. ================================================ FILE: items/key-asset.rst ================================================ .. _doc_item_asset_key: Key Assets ========== Keys are created from the ItemKeyAsset class. They are intended to be used as a part of the Steam Economy, rather than as in-game content. As such, none of its unique properties can be properly utilized by modders. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Key``) **ID** *uint16*: Must be a unique identifier. Key Asset Properties -------------------- **Exchange_With_Target_Item** *flag*: Adds UI elements for using this Steam Economy item on another Steam Economy item. ================================================ FILE: items/library-asset.rst ================================================ .. _doc_item_asset_library: Library Assets ============== Libraries are created from the ItemLibraryAsset class. They are placeable storage containers for experience points. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Library``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Library``) **ID** *uint16*: Must be a unique identifier. Library Asset Properties ------------------------ **Capacity** *uint32*: Maximum amount of experience points that can be stored. **Tax** *byte*: Percentage of the deposit that is taxed. Defaults to 0. ================================================ FILE: items/magazine-asset.rst ================================================ .. _doc_item_asset_magazine: Magazine Assets =============== Magazines (or "magazine attachments") are created from the ItemMagazineAsset class. They can be attached to ranged weapons. This inherits the :ref:`CaliberAsset ` class. Game Data File -------------- Magazine attachments inherit properties from the CaliberAsset class, which in turn inherits properties from the ItemAsset class. Properties that are required to be included are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Magazine`` Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Animal_Damage ` - :ref:`float32 ` - ``0`` * - :ref:`Barricade_Damage ` - :ref:`float32 ` - ``0`` * - :ref:`Delete_Empty ` - :ref:`flag ` - * - :ref:`Explosion ` - :ref:`doc_data_guid` or :ref:`uint16 ` - ``0`` * - :ref:`Explosion_Launch_Speed ` - :ref:`float32 ` - See description * - :ref:`Explosion_Penetrate_Buildables ` - :ref:`bool ` - ``false`` * - :ref:`Explosion_Plays_Impact_Effects ` - :ref:`bool ` - ``true`` * - :ref:`Explosive ` - :ref:`flag ` - * - :ref:`Impact ` - :ref:`doc_data_guid` or :ref:`uint16 ` - ``0`` * - :ref:`Object_Damage ` - :ref:`float32 ` - See description * - :ref:`Pellets ` - :ref:`uint8 ` - ``1`` * - :ref:`Player_Damage ` - :ref:`float32 ` - ``0`` * - :ref:`Projectile_Blast_Radius_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Projectile_Damage_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Projectile_Launch_Force_Multiplier ` - :ref:`float32 ` - ``1`` * - :ref:`Range ` - :ref:`float32 ` - ``0`` * - :ref:`Resource_Damage ` - :ref:`float32 ` - ``0`` * - :ref:`Should_Fill_After_Detach ` - :ref:`bool ` - ``false`` * - :ref:`Spawn_Explosion_On_Dedicated_Server ` - :ref:`flag ` - * - :ref:`Speed ` - :ref:`float32 ` - ``1`` * - :ref:`Structure_Damage ` - :ref:`float32 ` - ``0`` * - :ref:`Stuck ` - :ref:`uint8 ` - ``0`` * - :ref:`Tracer ` - :ref:`doc_data_guid` or :ref:`uint16 ` - ``0`` * - :ref:`Vehicle_Damage ` - :ref:`float32 ` - ``0`` * - :ref:`Zombie_Damage ` - :ref:`float32 ` - ``0`` Property Descriptions ````````````````````` .. _doc_item_asset_magazine:animal_damage: Animal_Damage :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Damage dealt to animals caught within the area-of-effect explosion of a magazine attachment using the ``Explosive`` flag. ---- .. _doc_item_asset_magazine:barricade_damage: Barricade_Damage :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Damage dealt to barricades caught within the area-of-effect explosion of a magazine attachment using the ``Explosive`` flag. ---- .. _doc_item_asset_magazine:delete_empty: Delete_Empty :ref:`flag ` :::::::::::::::::::::::::::::::::::::::: The magazine attachment should be deleted when it is fully depleted. ---- .. _doc_item_asset_magazine:explosion: Explosion :ref:`doc_data_guid` or :ref:`uint16 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of the effect that should be used for explosions caused by magazine attachment using the ``Explosive`` flag. ---- .. _doc_item_asset_magazine:explosion_launch_speed: Explosion_Launch_Speed :ref:`float32 ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Players caught within the area-of-effect explosion caused by projectiles when using the ``Explosive`` property are launched at this speed, in meters per second. Defaults to the resulting value of ``Player_Damage * 0.1``. ---- .. _doc_item_asset_magazine:explosion_penetrate_buildables: Explosion_Penetrate_Buildables :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, explosion damage passes through buildable items. ---- .. _doc_item_asset_magazine:explosion_plays_impact_effects: Explosion_Plays_Impact_Effects :ref:`bool ` ``true`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, per-surface effects like blood splatter are created. Defaults to true, but can be disabled particularly if a performance issue (e.g., an explosive many-pellet shotgun shell). ---- .. _doc_item_asset_magazine:explosive: Explosive :ref:`flag ` ::::::::::::::::::::::::::::::::::::: When this flag is included, the projectile fired from a ballistics projectile weapon will cause an area-of-effect explosion. This is typically used alongside the ``Range`` property. ---- .. _doc_item_asset_magazine:impact: Impact :ref:`doc_data_guid` or :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of the effect that should be play on impact. ---- .. _doc_item_asset_magazine:object_damage: Object_Damage :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Damage dealt to players caught within the area-of-effect explosion of a magazine attachment using the ``Explosive`` flag. Defaults to the value of the ``Resource_Damage`` property. ---- .. _doc_item_asset_magazine:pellets: Pellets :ref:`uint8 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Number of bullet rays shot. ---- .. _doc_item_asset_magazine:player_damage: Player_Damage :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Damage dealt to players caught within the area-of-effect explosion of a magazine attachment using the ``Explosive`` flag. ---- .. _doc_item_asset_magazine:projectile_blast_radius_multiplier: Projectile_Blast_Radius_Multiplier :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the blast radius of the explosive projectiles fired from physics projectile weapons. ---- .. _doc_item_asset_magazine:projectile_damage_multiplier: Projectile_Damage_Multiplier :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the damage dealt by the explosive projectiles fired from physics projectile weapons. ---- .. _doc_item_asset_magazine:projectile_launch_force_multiplier: Projectile_Launch_Force_Multiplier :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on the launch force applied to the explosive projectiles fired from physics projectile weapons. ---- .. _doc_item_asset_magazine:range: Range :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::: In meters, the radius of the area-of-effect explosion caused by a projectile when a magazine attachment is using the ``Explosive`` flag. ---- .. _doc_item_asset_magazine:resource_damage: Resource_Damage :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Damage dealt to resources caught within the area-of-effect explosion of a magazine attachment using the ``Explosive`` flag. ---- .. _doc_item_asset_magazine:should_fill_after_detach: Should_Fill_After_Detach :ref:`bool ` ``false`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Ammunition should be fully refilled after the magazine attachment is detached from a ranged weapon. ---- .. _doc_item_asset_magazine:spawn_explosion_on_dedicated_server: Spawn_Explosion_On_Dedicated_Server :ref:`flag ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: When using the ``Explosion`` property, spawn the explosion effect on the server. ---- .. _doc_item_asset_magazine:speed: Speed :ref:`float32 ` ``1`` ::::::::::::::::::::::::::::::::::::::::::::::::::: Multiplier on reload speed. ---- .. _doc_item_asset_magazine:structure_damage: Structure_Damage :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Damage dealt to structures caught within the area-of-effect explosion of a magazine attachment using the ``Explosive`` flag. ---- .. _doc_item_asset_magazine:stuck: Stuck :ref:`uint8 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::: The amount of quality that should be lost after the projectile hits something. When this value is greater than ``0``, the item will have a visible quality value. This property is typically used with :ref:`ranged weapons ` utilizing the ``Action String`` key-value pair, such as a crossbow. ---- .. _doc_item_asset_magazine:tracer: Tracer :ref:`doc_data_guid` or :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: GUID or legacy ID of the effect that should be used for bullet tracers. ---- .. _doc_item_asset_magazine:vehicle_damage: Vehicle_Damage :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Damage dealt to vehicles caught within the area-of-effect explosion of a magazine attachment using the ``Explosive`` flag. ---- .. _doc_item_asset_magazine:zombie_damage: Zombie_Damage :ref:`float32 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Damage dealt to zombies caught within the area-of-effect explosion of a magazine attachment using the ``Explosive`` flag. Unity_Setup ----------- Projectile.prefab: Optional for projectile-launching guns. If included, overrides the projectile instantiated when the gun is fired. ================================================ FILE: items/map-asset.rst ================================================ .. _doc_item_asset_map: Map Assets ========== Maps and compasses are created from the ItemMapAsset class. They provide the player with additional UI information for as long as they are in the player's inventory. They can neither be held nor equipped. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Map``, ``Compass``) **ID** *uint16*: Must be a unique identifier. Map Asset Properties -------------------- **Enables_Map** *flag*: Provides access to a satellite map display. **Enables_Chart** *flag*: Provides access to a chart map display. **Enables_Compass** *flag*: Provides a compass HUD, and the ability to set visible waypoints on the map display. ================================================ FILE: items/mask-asset.rst ================================================ .. _doc_item_asset_mask: Mask Assets =========== Masks are created from the ItemMaskAsset class. They can be worn by players and zombies. This inherits the :ref:`GearAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Mask``) **Useable** *enum* (``Clothing``) **ID** *uint16*: Must be a unique identifier. Mask Asset Properties --------------------- **Earpiece** *flag*: Specified if mask allows for listening on communications by walkie-talkie. **FilterDegradationRateMultiplier** *float32*: Multiplier for how quickly deadzones deplete a gasmask's filter quality. For example, 2 is faster (2x) and 0.5 is slower. ================================================ FILE: items/medical-asset.rst ================================================ .. _doc_item_asset_medical: Medical Assets ============== Medical items (or "medicine") are created from the ItemMedicalAsset class. They are irreversibly consumed by the player on use, and directly affect a player's stats such as health or immunity. This inherits the :ref:`ConsumeableAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Medical``) **Useable** *enum* (``Consumeable``) **ID** *uint16*: Must be a unique identifier. Medical Asset Properties ------------------------ Medicine have no unique asset properties. Refer to parent classes for additional properties. ================================================ FILE: items/melee-asset.rst ================================================ .. _doc_item_asset_melee: Melee Assets ============ Melees (or "melee weapons") are created from the ItemMeleeAsset class. They can be used as a source of damage. Melee weapons always show quality. This inherits the :ref:`WeaponAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Melee``) **Useable** *enum* (``Melee``) **Slot** :ref:`ESlotType ` (``None``, ``Primary``, ``Secondary``, ``Any``): Most melee weapons, including vanilla items, use ``Secondary``. This allows the weapon to be used from either the character's primary or secondary slot. **ID** *uint16*: Must be a unique identifier. Melee Asset Properties ---------------------- **Alert_Radius** *float*: The radius where zombies and animals should be alerted when attacking, measured in meters. Defaults to 8. **AttackAudioClip** :ref:`Master Bundle Pointer `: AudioClip to play when attacking. **ImpactAudioDef** :ref:`Master Bundle Pointer `: AudioClip or OneShotAudioDefinition to play upon impact. **Light** *flag*: Provides a toggleable flashlight, and allows for using :ref:`PlayerSpotLightConfig ` properties. **Repair** *flag*: Repairs barricades, structures, and vehicles. **Repeated** *flag*: The melee weapon's strong attack is disabled, and its weak attack will deal damage continuously. **Stamina** *byte*: Amount of stamina depleted with each attack. Defaults to 0. **Strength** *float*: Multiplier on the damage dealt by strong attacks. **Strong** *float*: Multiplier for the strong attack animation length, for when to apply damage. Defaults to 0.33. **Weak** *float*: Multiplier for the weak attack animation length, for when to apply damage. Defaults to 0.5. NPC Rewards ----------- For more information, refer to the :ref:`Rewards ` documentation. Rewards can be granted for weak and/or strong attacks. ``Weak_Attack_Quest_Rewards #`` with ``Weak_Attack_Quest_Reward_`` prefix or ``Strong_Attack_Quest_Rewards #`` with ``Strong_Attack_Quest_Reward_`` prefix. ================================================ FILE: items/oil-pump-asset.rst ================================================ .. _doc_item_asset_oil_pump: Oil Pump Assets =============== Oil pumps are created from the ItemOilPumpAsset class. They are placeables capable of creating fuel. When powered, oil pumps generate fuel over time. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Oil_Pump``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Oil``) **ID** *uint16*: Must be a unique identifier. Oil Pump Asset Properties ------------------------- **Fuel_Capacity** *uint16*: Maximum units of fuel that can be stored in the oil pump. Defaults to 0. ================================================ FILE: items/optic-asset.rst ================================================ .. _doc_item_asset_optic: Optic Assets ============ Optics are created from the ItemOpticAsset class. They can modify a player's view. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Optic``) **Useable** *enum* (``Optic``) **ID** *uint16*: Must be a unique identifier. Sight Asset Properties ---------------------- **Zoom** *float*: Multiplicative amount of zoom. Defaults to 1. ================================================ FILE: items/pants-asset.rst ================================================ .. _doc_item_asset_pants: Pants Assets ============ Pants are created from the ItemPantsAsset class. They can be worn by players and zombies. This inherits the :ref:`BagAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Pants``) **Useable** *enum* (``Clothing``) **ID** *uint16*: Must be a unique identifier. Pants Asset Properties ---------------------- Pants have no unique asset properties. Refer to parent classes for additional properties. ================================================ FILE: items/placeable-asset.rst ================================================ .. _doc_item_asset_placeable: Placeable Assets ================ The ItemPlaceableAsset class is a base class that other classes are derived from. Placeables are able to be placed by players. This inherits the :ref:`ItemAsset ` class. Placeable Asset Properties -------------------------- **ExplosionEffect_CopyModelPosition** *bool*: If true, effect spawns exactly at the model position without any offset. Defaults to false for backwards compatibility. **ExplosionEffect_CopyModelRotation** *bool*: If true, effects spawns with same rotation as the model. Defaults to false for backwards compatibility. **Item_Dropped_On_Destroy** :ref:`Asset Pointer `: Item asset or spawn table for items dropped when destroyed. This property can also be set to a string value of ``this``, which will use the the owning item's GUID. Useful to avoid accidentally writing the wrong ID. **Min_Items_Dropped_On_Destroy** *int*: Minimum number of items to drop when destroyed. Defaults to 0. **Max_Items_Dropped_On_Destroy** *int*: Maximum number of items to drop when destroyed. Defaults to 0. **Items_Dropped_On_Destroy** *int*: Shorthand for setting both ``Min_Items_Dropped_On_Destroy`` and ``Max_Items_Dropped_On_Destroy``. **Min_Items_Recovered_On_Salvage** *int*: Minimum number of items to receive when picked up below 100% health. Defaults to 1. **Max_Items_Recovered_On_Salvage** *int*: Maximum number of items to receive when picked up below 100% health. Defaults to 1. **Items_Recovered_On_Salvage** *int*: Shorthand for setting both ``Min_Items_Recovered_On_Salvage`` and ``Max_Items_Recovered_On_Salvage``. **Min_Items_Recovered_On_Salvage_Full_Health** *int*: Minimum number of items to receive when picked up at 100% health. Defaults to 1. **Max_Items_Recovered_On_Salvage_Full_Health** *int*: Maximum number of items to receive when picked up at 100% health. Defaults to 1. **Items_Recovered_On_Salvage_Full_Health** *int*: Shorthand for setting both ``Min_Items_Recovered_On_Salvage_Full_Health`` and ``Max_Items_Recovered_On_Salvage_Full_Health``. **PlaceableProvidesCraftingTags** list of :ref:`Asset Pointer `: :ref:`doc_assets_tag` available to nearby players for blueprint requirements. Tags are listed in the item description as "crafting capabilities." For example, the vanilla Brick Oven provides two tags: .. code-block:: unturneddat PlaceableProvidesCraftingTags [ // Heat Source (for backwards compatibility) 20f30322bbcc4b01a4f116d22b24c21a // Enclosed Heat Source d2cc65b749e5477f95103601df89cdbc ] **SalvageItem** :ref:`Asset Pointer `: Override the default salvaging behavior by pointing to a specific item or spawn table that should be added when salvaging a placeable that is below 100% health. By default, this property will choose a random item used in the placeable's blueprints. **SalvageItem_FullHealth** :ref:`Asset Pointer `: Defaults to self. Overrides the default pickup behavior by pointing to a specific item or spawn table that should be added when salvaging a placeable that is at 100% health. This property can also be set to a string value of ``this``, which will use the the owning item's GUID. Useful to avoid accidentally writing the wrong ID. ================================================ FILE: items/refill-asset.rst ================================================ .. _doc_item_asset_refill: Refill Assets ============= Refills (localized as "water canisters") are created from the ItemRefillAsset class. They are useables able to siphon, store, and deposit water. Players can also drink from water canisters in order to restore their status bars. Water canisters have four potential states: empty, salty, dirty, or clean. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Refill``) **Useable** *enum* (``Refill``) **ID** *uint16*: Must be a unique identifier. Refill Asset Properties ----------------------- **ConsumeAudioClip** :ref:`Master Bundle Pointer `: AudioClip to play when the consumeable is used. **Clean_Food** *float*: Amount of food restored when drinking clean water. **Clean_Health** *float*: Amount of health restored when drinking clean water. **Clean_Oxygen** *float*: Amount of oxygen restored when drinking clean water. **Clean_Stamina** *float*: Amount of stamina restored when drinking clean water. **Clean_Virus** *float*: Amount of immunity depleted when drinking clean water. **Clean_Water** *float*: Amount of water restored when drinking clean water. **Dirty_Food** *float*: Amount of food restored when drinking dirty water. Defaults to the result of ``Clean_Food * 0.6``. **Dirty_Health** *float*: Amount of health restored when drinking dirty water. Defaults to the result of ``Clean_Health * 0.6``. **Dirty_Oxygen** *float*: Amount of oxygen restored when drinking dirty water. Defaults to the result of ``Clean_Oxygen * 0.6``. **Dirty_Stamina** *float*: Amount of stamina restored when drinking dirty water. Defaults to the result of ``Clean_Stamina * 0.6``. **Dirty_Virus** *float*: Amount of immunity depleted when drinking dirty water. Defaults to the result of ``Clean_Virus * -0.399999976``. **Dirty_Water** *float*: Amount of water restored when drinking dirty water. Defaults to the result of ``Clean_Water * 0.6``. **Salty_Food** *float*: Amount of food restored when drinking salty water. Defaults to the result of ``Clean_Food * 0.25``. **Salty_Health** *float*: Amount of health restored when drinking salty water. Defaults to the result of ``Clean_Health * 0.25``. **Salty_Oxygen** *float*: Amount of oxygen restored when drinking salty water. Defaults to the result of ``Clean_Oxygen * 0.25``. **Salty_Stamina** *float*: Amount of stamina restored when drinking salty water. Defaults to the result of ``Clean_Stamina * 0.25``. **Salty_Virus** *float*: Amount of immunity depleted when drinking salty water. Defaults to the result of ``Clean_Virus * -0.75``. **Salty_Water** *float*: Amount of water restored when drinking salty water. Defaults to the result of ``Clean_Water * 0.25``. .. deprecated:: 3.20.9.0 **Water** *byte*: Deprecated in favor of ``Clean_Water``. When this property is used, its value is assigned to ``Clean_Water`` instead. ================================================ FILE: items/sentry-asset.rst ================================================ .. _doc_item_asset_sentry: Sentry Assets ============= Sentries (localized as "robotic turrets") are created from the ItemSentryAsset class. They are placeables that can automatically detect, track, and attack target under certain conditions. Storing a ranged weapon inside a sentry allows it to use that weapon when attacking target. This inherits the :ref:`StorageAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Sentry``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Sentry``, ``Sentry_Freeform``) **ID** *uint16*: Must be a unique identifier. Sentry Asset Properties ----------------------- **Detection_Radius** *float*: Radius for initially detecting targets, in meters. Defaults to 48. **Mode** *enum* (``Friendly``, ``Neutral``, ``Hostile``): The sentry's "Mode" determines what the sentry considers a valid target. Defaults to ``Mode Neutral``. **Infinite_Ammo** *bool*: Whether or not the magazine attachments in the stored ranged weapon should be depleted during use. If true, the ranged weapon has infinite ammo and any attached magazine attachment will not be depleted during use. Defaults to false. **Infinite_Quality** *bool*: Whether or not the stored ranged weapon should degrade during use. If true, the ranged weapon's quality will not degrade during use. Defaults to false. **Requires_Power** *bool*: Whether or not the sentry requires power from a generator. If true, the sentry must be powered in order for it to detect, track, and attack targets. Defaults to true. **Target_Acquired_Effect** :ref:`Asset Pointer `: The audio effect played when a target is detected. Defaults to ab5f0056b54545c8a051159659da8bea. **Target_Animals** *bool*: If true, this sentry can attack animals. Defaults to true. **Target_Lost_Effect** :ref:`Asset Pointer `: The audio effect played when a target is no longer detected. Defaults to 288b98b718084699ba3653c592e57803. **Target_Loss_Radius** *float*: Radius for continuing to track targets after they have left the initial detection radius, in meters. Defaults to ``Detection_Radius * 1.2f`` (i.e., 20% higher than ``Detection_Radius``). **Target_Players** *bool*: If true, this sentry can attack players. Defaults to true. **Target_Vehicles** *bool*: If true, this sentry can attack vehicles. Defaults to true. **Target_Zombies** *bool*: If true, this sentry can attack zombies. Defaults to true. **Sentry_Bypasses_PvE** *bool*: If true, sentry can damage players and vehicles in PvE mode. Defaults to false. **React_To_Attacks** *bool*: If true, sentry immediately focuses on attacking player. Defaults to false. **Sweep_Yaw** *float*: Yaw range the sentry sweeps left/right. Defaults to 120. **Sweep_Period** *float*: How long in seconds for the sentry to complete a sweep from left to right and back. Defaults to 6.3 seconds. ================================================ FILE: items/shirt-asset.rst ================================================ .. _doc_item_asset_shirt: Shirt Assets ============ Shirts are created from the ItemShirtAsset class. They can be worn by players and zombies. This inherits the :ref:`BagAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Shirt``) **Useable** *enum* (``Clothing``) **ID** *uint16*: Must be a unique identifier. Shirt Asset Properties ---------------------- **Ignore_Hand** *flag*: Specified if shirt should ignore a player's left-handed setting. Body Mesh Replacements ---------------------- For the full documentation, refer to the :ref:`Character Mesh Replacement ` documentation. **Has_1P_Character_Mesh_Override** *bool*: A prefab named "Character_Mesh_1P_Override_0" should be loaded. Defaults to false. **Character_Mesh_3P_Override_LODs** *uint16*: Number of prefabs to load for each LOD index. Defaults to 0. **Has_Character_Material_Override** *bool*: A material named "Character_Material_Override" should be loaded to replace the first-person and third-person mesh materials. Defaults to false. ================================================ FILE: items/sight-asset.rst ================================================ .. _doc_item_asset_sight: Sight Assets ============ Sights (or "sight attachments") are created from the ItemSightAsset class. They are inventory items that can be attached to ranged weapons. This inherits the :ref:`CaliberAsset ` class. Game Data File -------------- Sight attachments inherit properties from the CaliberAsset class, which in turn inherits properties from the ItemAsset class. Properties that are required to be included are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Sight`` Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`AimAlignment_LocalOffset ` - :ref:`Vector3 ` - ``(0, 0, 0)`` * - :ref:`AimAlignment_Owner ` - :ref:`EAimAlignmentTransformOwner ` - ``Sight`` * - :ref:`AimAlignment_Path ` - :ref:`string ` - ``Model_0/Aim`` * - :ref:`DistanceMarkers ` - :ref:`list of DistanceMarker ` - * - :ref:`Holographic ` - :ref:`flag ` - * - :ref:`Nightvision_Color ` - :ref:`color ` - See description * - :ref:`Nightvision_Fog_Intensity ` - :ref:`float32 ` - See description * - :ref:`Offset_Scope_Overlay_By_One_Texel ` - :ref:`bool ` - ``false`` * - :ref:`Vision ` - :ref:`ELightingVision ` - ``None`` * - :ref:`Zoom ` - :ref:`float32 ` - ``1`` * - :ref:`ThirdPerson_Zoom ` - :ref:`float32 ` - ``1.25`` * - :ref:`Zoom_Using_Eyes ` - :ref:`bool ` - ``false`` .. _doc_item_asset_sight:distancemarker_dictionary: DistanceMarker Dictionary ````````````````````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Distance ` - :ref:`float32 ` - ``0`` * - :ref:`LineOffset ` - :ref:`float32 ` - ``0`` * - :ref:`LineWidth ` - :ref:`float32 ` - ``0.05`` * - :ref:`Side ` - :ref:`ESide ` - ``Right`` * - :ref:`HasLabel ` - :ref:`bool ` - ``true`` * - :ref:`Color ` - :ref:`color ` - ``black`` .. _doc_item_asset_sight:eaimalignmenttransformowner: EAimAlignmentTransformOwner Enumeration ```````````````````````````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``Sight`` - Look for aim alignment transform relative to sight model. Defaults to Model_0/Aim. * - ``Gun`` - Look for aim alignment transform relative to equipable prefab. Requires setting AimAlignment_Path. .. _doc_item_asset_sight:eside_enumeration: ESide Enumeration ````````````````` .. list-table:: :widths: 25 75 :header-rows: 1 * - Named Value - Description * - ``Left`` - Marking extends to the left from the center. * - ``Right`` - Marking extends to the right from the center. Property Descriptions ````````````````````` .. _doc_item_asset_sight:aimalignment_localoffset: AimAlignment_LocalOffset :ref:`Vector3 ` ``(0, 0, 0)`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Position offset relative to Aim transform or transform specified by ``AimAlignment_Path``. ---- .. _doc_item_asset_sight:aimalignment_owner: AimAlignment_Owner :ref:`EAimAlignmentTransformOwner ` ``Sight`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Controls where to find ``AimAlignment_Path``. ---- .. _doc_item_asset_sight:aimalignment_path: AimAlignment_Path :ref:`string ` ``Model_0/Aim`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: While aiming down sights, the camera's position is aligned with this transform. Relative to ``AimAlignment_Owner``. ---- .. _doc_item_asset_sight:distancemarkers: DistanceMarkers :ref:`list of DistanceMarker ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: This property is a list of :ref:`DistanceMarker dictionaries `. It can be used to add visible (and accurate) distance markers to the scope that account for the weapon's bullet drop. ---- .. _doc_item_asset_sight:holographic: Holographic :ref:`flag ` ::::::::::::::::::::::::::::::::::::::: This sight should be holographic. ---- .. _doc_item_asset_sight:nightvision_color: Nightvision_Color :ref:`color ` ::::::::::::::::::::::::::::::::::::::::::::::: Override the default nightvision color. To configure this property, the ``Vision`` property must be set to ``Military``. This property supports using legacy color parsing. When not overridden, the default nightivision color will depend on the value of the :ref:`Vision ` property. ---- .. _doc_item_asset_sight:nightvision_fog_intensity: Nightvision_Fog_Intensity :ref:`float32 ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Configure the intensity of fog while nightvision is active. When this property has not been configured, the default fog intensity will depend on the value of the :ref:`Vision ` property. ---- .. _doc_item_asset_sight:offset_scope_overlay_by_one_texel: Offset_Scope_Overlay_By_One_Texel :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: If ``true``, the 2D scope texture will be scaled up slightly to center the pixel that would otherwise be left of center. For example, when enabled with a 512×512 texture the pixel at 255×255 will be centered on the display. ---- .. _doc_item_asset_sight:vision: Vision :ref:`ELightingVision ` ``None`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Set a unique lighting vision effect to use. The value of this property may effect the default values of other properties. The ``Headlamp`` enumerator is not supported by this property. ---- .. _doc_item_asset_sight:zoom: Zoom :ref:`float32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::: Multiplicative amount of zoom. This value must be equal to or greater than ``1``. ---- .. _doc_item_asset_sight:thirdperson_zoom: ThirdPerson_Zoom :ref:`float32 ` ``1.25`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Zoom factor while in the third-person perspective. This value must be equal to or greater than ``1``. ---- .. _doc_item_asset_sight:zoom_using_eyes: Zoom_Using_Eyes :ref:`bool ` ``false`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Whether the main camera field of view should zoom without a scope overlay. .. _doc_item_asset_sight:distancemarker_dictionary_descriptions: DistanceMarker Dictionary Descriptions `````````````````````````````````````` .. _doc_item_asset_sight:distancemarker_distance: Distance :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::: Meters between the player and a hypothethical target. ---- .. _doc_item_asset_sight:distancemarker_lineoffset: LineOffset :ref:`float32 ` ``0`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Distance between center line and start of horizontal line marker. Display-related properties like ``LineOffset`` are a percentage (represented as a decimal value from 0 to 1). For example, ``0.25`` would be 25%. ---- .. _doc_item_asset_sight:distancemarker_linewidth: LineWidth :ref:`float32 ` ``0.05`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Length of horizontal line marker. Display-related properties like ``LineWidth`` are a percentage (represented as a decimal value from 0 to 1). For example, ``0.25`` would be 25%. ---- .. _doc_item_asset_sight:distancemarker_side: Side :ref:`ESide ` ``Right`` :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Direction the horizontal line and text expand in. ---- .. _doc_item_asset_sight:distancemarker_haslabel: HasLabel :ref:`bool ` ``true`` :::::::::::::::::::::::::::::::::::::::::::::::::::::: If true, a label with ``Distance`` text is shown next to the horizontal line marker. ---- .. _doc_item_asset_sight:distancemarker_color: Color :ref:`color ` ``black`` ::::::::::::::::::::::::::::::::::::::::::::: Override the color of the horizontal line and text. ================================================ FILE: items/storage-asset.rst ================================================ .. _doc_item_asset_storage: Storage Assets ============== Storages (localized as "item storages") are created from the ItemStorageAsset class. They are placeables used to store items. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Storage``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Storage``, ``Storage_Wall``) **ID** *uint16*: Must be a unique identifier. Storage Asset Properties ------------------------ **Can_Players_Open** *bool*: If true, players can interact with the barricade to open storage. Defaults to true. Useful for pre-placed sentries to prevent stealing their guns. **Delete_Contained_Items_On_Destroy** *bool*: If true, any stored items are despawned rather than dropped when destroyed. Defaults to false. **Display** *flag*: If specified, the first item in the storage will be visibly displayed. **Should_Close_When_Outside_Range** *bool*: Whether or not the storage should automatically close when the player is outside of the interaction range. Defaults to false. **Storage_X** *byte*: Number of columns (horizontal storage space). Defaults to 0. **Storage_Y** *byte*: Number of rows (vertical storage space). Defaults to 0. **Default_Contained_Items** *list of dictionaryies*: Items to create inside storage when first spawned. Each item can contain the following properties: - **Asset**: :ref:`Asset Pointer `: Item or spawn table to grant an item from. - **Amount** *int*: Number of times to grant this item. Defaults to 1. - **Origin** :ref:`EItemOrigin `: Determines starting state of the item. Defaults to World. ================================================ FILE: items/structure-asset.rst ================================================ .. _doc_item_asset_structure: Structure Assets ================ Structures are created from the ItemStructureAsset class. They can be placed by players. Some structure pieces require another structure piece in order to be placed. This inherits the :ref:`PlaceableAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Structure``): When intending to use a child class, refer to that class's documentation instead for the proper enumerator to use. **Useable** *enum* (``Structure``) **Construct** *enum* (``Floor``, ``Floor_Poly``, ``Pillar``, ``Post``, ``Rampart``, ``Roof``, ``Roof_Poly``, ``Wall``): Determines how this structure can be placed, and how other structure pieces can snap to it. **ID** *uint16*: Must be a unique identifier. **InventoryAudio** :ref:`Master Bundle Pointer `: See :ref:`ItemAsset ` for full documentation. Defaults to ``Sounds/Inventory/SmallMetal.asset`` if the name contains the word "Metal", to ``Sounds/Inventory/LightMetalEquipment.asset`` if either ``Size_X`` or ``Size_Y`` value is equal to 1, to ``Sounds/Inventory/MediumMetalEquipment.asset`` if either ``Size_X`` or ``Size_Y`` value is less than or equal to 2, or ``Sounds/Inventory/HeavyMetalEquipment.asset`` if none of the criteria is met. Structure Asset Properties -------------------------- **Armor_Tier** *enum* (``Low``, ``High``): Armor is a multiplier on damage received. A structure's armor tier can either be low-tier or high-tier. By default, structures with low-tier armor take 100% of the damage they receive, while structures with high-tier armor take 50% of the damage they receive. These multipliers can be configured in the `gameplay config `_. Defaults to low-tier, except when the structure's name contains the word "Metal" or "Brick". **Can_Be_Damaged** *bool*: If true, this structure can be damaged. Defaults to true. **Can_Zombies_Target** *bool*: If true, this item is eligible for zombies to detect and attack when stuck. Defaults to true. **Eligible_For_Pooling** *bool*: If true, this structure is eligible for object pooling. Some structures may not reset properly when pooling is enabled. Defaults to true. **Explosion** :ref:`GUID ` or *uint16*: GUID or legacy ID of :ref:`EffectAsset ` to play when destroyed. **Foliage_Cut_Radius** *float*: In meters, the radius around the structure where foliage is removed. Defaults to 6. **Has_Clip_Prefab** *bool*: Whether or not the structure has a Clip.prefab. If the structure should use the same prefab on the server as on the client, set to false. For example, most official content uses ``Has_Clip_Prefab false``. Defaults to true. **Health** *uint16*: Total health value. Defaults to 0. **PlacementAudioClip** :ref:`Master Bundle Pointer `: AudioClip to play when the structure is placed. **PlacementPreviewPrefab** :ref:`Master Bundle Pointer `: Overrides the placement preview model spawned when this item is held. **Proof_Explosion** *flag*: Immune to area-of-effect explosive damage. **Range** *float*: In meters, the maximum distance away the structure can be placed from the player. **Salvage_Duration_Multiplier** *float*: Multiplier on how long it takes to salvage this structure. Setting this to a larger number will cause salvaging to take longer. Defaults to 1. **Terrain_Test_Height** *float*: Length of the raycast downward from the pivot to check if the floor is above terrain. This is the maximum distance a floor can be placed above terrain, in meters. Defaults to 10. **Unpickupable** *flag*: Disables the ability to pick up a placed structure. **Unrepairable** *flag*: Cannot be repaired by a :ref:`MeleeAsset ` with the ``Repair`` flag. For example, the `Blowtorch `_ would not be able to repair this structure. **Unsalvageable** *flag*: Salvaging a damaged structure yields no partial resources. **Unsaveable** *flag*: This structure is excluded from being saved. **Vulnerable** *flag*: The structure can be damaged by lower-power weapons that do not have the ``Invulnerable`` flag. **Requires_Pillars** *bool*: Whether or not a valid wall placement requires pillars. If true, two pillars are required for a valid placement. Defaults to true. ================================================ FILE: items/supply-asset.rst ================================================ .. _doc_item_asset_supply: Supply Assets ============= Supplies (or "crafting supplies") are created from the ItemSupplyAsset class. They are items primarily intended to be used as ingredients in crafting blueprints. They can neither be held nor equipped. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Supply``) **ID** *uint16*: Must be a unique identifier. Supply Asset Properties ----------------------- Crafting supplies have no unique asset properties. Refer to :ref:`item asset documentation ` for additional properties. ================================================ FILE: items/tactical-asset.rst ================================================ .. _doc_item_asset_tactical: Tactical Assets =============== Tacticals (or "tactical attachments") are created from the ItemTacticalAsset class. They are inventory items that can be attached to ranged weapons. This inherits the :ref:`CaliberAsset ` class. Game Data File -------------- Tactical attachments inherit properties from the CaliberAsset class, which in turn inherits properties from the ItemAsset class. Properties that are required to be included are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Tactical`` Properties `````````` .. list-table:: :widths: 40 40 20 :header-rows: 1 * - Property Name - Type - Default Value * - :ref:`Laser ` - :ref:`flag ` - * - :ref:`Laser_Color ` - :ref:`color ` - ``#FF0000`` * - :ref:`Light ` - :ref:`flag ` - * - :ref:`Melee ` - :ref:`flag ` - * - :ref:`Rangefinder ` - :ref:`flag ` - Property Descriptions ````````````````````` .. _doc_item_asset_tactical:laser: Laser :ref:`flag ` ::::::::::::::::::::::::::::::::: Provides a toggleable laser. ---- .. _doc_item_asset_tactical:laser_color: Laser_Color :ref:`color ` ``#FF0000`` ::::::::::::::::::::::::::::::::::::::::::::::::::::: Override the default red color with the specified value. This property supports using legacy color parsing. ---- .. _doc_item_asset_tactical:light: Light :ref:`flag ` ::::::::::::::::::::::::::::::::: Provides a toggleable flashlight, and allows for using :ref:`PlayerSpotLightConfig ` properties. ---- .. _doc_item_asset_tactical:melee: Melee :ref:`flag ` ::::::::::::::::::::::::::::::::: Provides the ability to perform a melee attack. This attack does 40 damage, and is not configurable. ---- .. _doc_item_asset_tactical:rangefinder: Rangefinder :ref:`flag ` ::::::::::::::::::::::::::::::::::::::: Provides a toggleable rangefinder. Melee-Specific Property Descriptions ````````````````````````````````````` .. note:: These properties are only applicable if the ``Melee`` flag is set. .. warning:: This is mostly copied 1:1 from :ref:`doc_item_asset_weapon` and should be tidied up if/when that is updated. **Melee_Range** *float32*: The maximum distance in meters before damage is no longer possible. **Melee_Player_Damage** *float32*: Amount of damage that should be dealt to player entities, prior to modifiers such as limb multipliers. **Melee_Player_Leg_Multiplier** *float32*: Multiplier on damage targeted against a player's legs. **Melee_Player_Arm_Multiplier** *float32*: Multiplier on damage targeted against a player's arms. **Melee_Player_Spine_Multiplier** *float32*: Multiplier on damage targeted against a player's torso. **Melee_Player_Skull_Multiplier** *float32*: Multiplier on damage targeted against a player's head. **Melee_Player_Damage_Bleeding** *enum* (``Always``, ``Default``, ``Heal``, ``Never``): Determines the effect the weapon has in relation to the "Bleeding" status effect. When using "Always", the Bleeding status effect will always be applied on hit. When using "Default", the Bleeding status effect will only be applied if the necessary damage threshold is met. When using "Heal", anyone hit by the weapon will have their Bleeding status effect removed. When using "Never", the Bleeding status effect is never applied by this weapon. Defaults to "Default" enumerator. **Melee_Player_Damage_Bones** *enum* (``Always``, ``Heal``, ``None``): Determines the effect the weapon has in relation to the "Broken Bones" status effect. When using "Always", the Broken Bones status effect will always be applied on hit. When using "Heal", anyone hit by the weapon will have their Broken Bones status effect removed. When using "Never", the Broken Bones status effect is never applied by this weapon. Defaults to the "None" enumerator. **Melee_Zombie_Damage** *float32*: Amount of damage that should be dealt to zombie entities, prior to modifiers such as limb multipliers. **Melee_Zombie_Leg_Multiplier** *float32*: Multiplier on damage targeted against a zombie's legs. **Melee_Zombie_Arm_Multiplier** *float32*: Multiplier on damage targeted against a zombie's arms. **Melee_Zombie_Spine_Multiplier** *float32*: Multiplier on damage targeted against a zombie's torso. **Melee_Zombie_Skull_Multiplier** *float32*: Multiplier on damage targeted against a zombie's head. **Melee_Zombie_Ragdoll_Force_Multiplier** *float32*: Scales force applied to zombie ragdoll. Defaults to 1. **Melee_Stun_Zombie_Always** *flag*: Specified if a zombie should always be stunned when targeted by the weapon. **Melee_Stun_Zombie_Never** *flag*: Specified if a zombie should never be stunned when targeted by the weapon. **Melee_Animal_Damage** *float32*: Amount of damage that should be dealt to animal entities, prior to modifiers such as limb multipliers. **Melee_Animal_Leg_Multiplier** *float32*: Multiplier on damage targeted against a animal's limbs. **Melee_Animal_Spine_Multiplier** *float32*: Multiplier on damage targeted against a animal's torso. **Melee_Animal_Skull_Multiplier** *float32*: Multiplier on damage targeted against a animal's head. ================================================ FILE: items/tank-asset.rst ================================================ .. _doc_item_asset_tank: Tank Assets =========== Tanks (localized as "liquid storages") are created from the ItemTankAsset class. They are placeables used to store water or fuel. Players can siphon from, or deposit into, a liquid storage with certain items. Fuel tanks require a :ref:`fuel canister `, while water tanks require a :ref:`water canister `. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Tank``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Tank``) **ID** *uint16*: Must be a unique identifier. Tank Asset Properties --------------------- **Resource** *uint16*: Maximum units of liquid that can be stored in the tank. One unit of water is the equivalent of one usage of a water canister. Defaults to 0. **Source** *enum* (``Fuel``, ``None``, ``Water``): Type of liquid that can be stored in the tank. ================================================ FILE: items/throwable-asset.rst ================================================ .. _doc_item_asset_throwable: Throwable Assets ================ Throwables are created from the ItemThrowableAsset class. They can be thrown by players. Throwables cannot be used in any safezones that disallow weapons. This inherits the :ref:`WeaponAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Throwable``) **Useable** *enum* (``Throwable``) **ID** *uint16*: Must be a unique identifier. Throwable Asset Properties -------------------------- **Boost_Throw_Force_Multiplier** *float*: A multiplier on the amount of throwing force when the player has the "Olympic" random boost. Defaults to 1.4. **Explode_On_Impact** *flag*: Specified if the throwable should immediately detonate upon impact. Robotic turrets using ``Mode Friendly`` will target players holding a throwable that has this flag. **Explosion** *uint16* or *GUID*: ID or GUID of explosion effect to play upon detonation. **Explosion_Launch_Speed** *float*: Velocity at which players are launched by area-of-effect explosions. Defaults to ``Player_Damage × 0.1``. **Explosive** *flag*: Specified if the throwable should have an area-of-effect explosion. Robotic turrets using ``Mode Friendly`` will target players holding a throwable that has this flag. **Flash** *flag*: Specified if the throwable should cause a flashbang effect for players caught within the area-of-effect. Robotic turrets using ``Mode Friendly`` will target players holding a throwable that has this flag. **Fuse_Length** *float*: A timer, in seconds, for the fuse length. Defaults to 180 seconds. If the throwable has the ``Explosive`` flag or the ``Flash`` flag, then it defaults to 2.5 seconds instead. **Sticky** *flag*: Specified if the throwable should stick to the environment, barricades, and structures. **Strong_Throw_Force** *float*: The amount of force throwables are thrown with when performing a strong throw, measured in Newtons. Defaults to 1100. **Weak_Throw_Force** *float*: The amount of force throwables are thrown with when performing a weak throw, measured in Newtons. Defaults to 600. ================================================ FILE: items/tire-asset.rst ================================================ .. _doc_item_asset_tire: Tire Assets =========== Tires (localized as "tools") are created from the ItemTireAsset class. They are useables that allow for adding and removing tires from vehicles. This inherits the :ref:`VehicleRepairToolAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Tire``) **Useable** *enum* (``Tire``) **ID** *uint16*: Must be a unique identifier. Tire Asset Properties --------------------- **Mode** *enum* (``Add``, ``Remove``): How the usable should interact with tires. ``Mode Add`` will consume the item to add a tire to the vehicle. ``Mode Remove`` allows the usable to remove tires, adding the corresponding item to the player's inventory. ================================================ FILE: items/tool-asset.rst ================================================ .. _doc_item_asset_tool: Tool Assets =========== Tools are created from the ItemToolAsset class. Their functionality depends on the configured ``Useable`` property. This inherits the :ref:`ItemAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Tool``): When intending to use a child class, refer to that class's documentation instead for the proper enumerator to use. **Useable** *enum* (``Carjack``, ``Carlockpick``, ``Housing_Planner``, ``Walkie_Talkie``): When using the ``Carjack`` enumerator, the tool can be used on vehicles to launch them upwards into the air. When using ``Carlockpick``, the tool can be used once on any locked vehicle in order to forcefully unlock it. When using ``Housing_Planner``, the tool can be used to quickly access :ref:`structure pieces ` from the player's own inventory. When using ``Walkie_Talkie``, the tool can be used to have long-distance voice chat communications with other players. **ID** *uint16*: Must be a unique identifier. Tool Asset Properties --------------------- Tools have no unique asset properties. Instead, refer to ``Useable`` for relevant configuration options. Refer to parent classes for additional properties. ================================================ FILE: items/trap-asset.rst ================================================ .. _doc_item_asset_trap: Trap Assets =========== Traps are created from ItemTrapAsset. They are placeable damage sources. This inherits the :ref:`BarricadeAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Trap``) **Useable** *enum* (``Barricade``) **Build** *enum* (``Spike``, ``Wire``) **ID** *uint16*: Must be a unique identifier. Trap Asset Properties --------------------- **Animal_Damage** *float*: Damage dealt to animals caught within the area-of-effect explosion. **Barricade_Damage** *float*: Damage dealt to barricades caught within the area-of-effect explosion. **Broken** *flag*: Players who trigger the trap will be inflicted with the `Broken Bones `_ status effect. **Damage_Tires** *flag*: This trap can pop the tires of vehicles that drive over it. **Explosion_Launch_Speed** *float*: Launch speed of players caught within the area-of-effect explosion, in meters per second. Defaults to the value of ``Player_Damage * 0.1``. **Explosion2** *uint16* or *GUID*: ID or GUID of effect to play upon detonation. **Explosive** *flag*: Specified if the trap should have an area-of-effect explosion when triggered. **Object_Damage** *float*: Damage dealt to objects caught within the area-of-effect explosion. Defaults to the value of ``Resource_Damage``. **Player_Damage** *float*: Damage dealt to players caught within the area-of-effect explosion. **Range2** *float*: In meters, the radius of the damaging, area-of-effect explosion. **Requires_Power** *bool*: Whether or not the trap requires power from a generator. Defaults to ``false``. Optionally, a "Powered" GameObject can be included in Unity. This GameObject is activated when powered, and deactivated when not powered. **Resource_Damage** *float*: Damage dealt to resources caught within the area-of-effect explosion. **Structure_Damage** *float*: Damage dealt to structures caught within the area-of-effect explosion. **Trap_Cooldown** *float*: In seconds, the time until trap is active again. **Trap_Setup_Delay** *float*: In seconds, delay before a trap becomes active after being placed. Defaults to 0.25 seconds. **Vehicle_Damage** *float*: Damage dealt to vehicles caught within the area-of-effect explosion. ================================================ FILE: items/vehicle-lockpick-tool-asset.rst ================================================ .. _doc_item_asset_vehicle_lockpick_tool: Vehicle Lockpick Tool Assets ============================= Vehicle lockpick tools are created from the ItemVehicleLockpickToolAsset class. They are useables for unlocking a vehicle. This inherits the :ref:`ToolAsset ` class. Vehicle Lockpick Tool Asset Properties -------------------------------------- **FailureProbability** *float*: Normalized percentage chance of lockpicking failing. Defaults to zero. The "Use_Failure" animation is played instead of "Use" if lockpicking fails. **FailureEffect** :ref:`doc_data_assetptr`: Effect to play when lockpicking fails. ================================================ FILE: items/vehicle-paint-tool-asset.rst ================================================ .. _doc_item_asset_vehicle_paint_tool: Vehicle Paint Tool Assets ========================= Vehicle paint tools are created from the ItemVehiclePaintToolAsset class. They are useables for changing the vehicle paint color. This inherits the :ref:`ToolAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Vehicle_Paint_Tool``) **Useable** *enum* (``Vehicle_Paint``) **ID** *uint16*: Must be a unique identifier. Vehicle Paint Tool Asset Properties ----------------------------------- **PaintColor** *color*: Vehicle's color will be replaced with this when used. ================================================ FILE: items/vehicle-repair-tool-asset.rst ================================================ .. _doc_item_asset_vehicle_repair_tool: Vehicle Repair Tool Assets ========================== Vehicle repair tools (localized as "tools") are created from the ItemVehicleRepairTool class. They are useables for replacing vehicle batteries. This inherits the :ref:`ToolAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Vehicle_Repair_Tool``) **Useable** *enum* (``Battery_Vehicle``) **ID** *uint16*: Must be a unique identifier. Vehicle Repair Tool Asset Properties ------------------------------------ Vehicle repair tools have no unique asset properties. Refer to parent classes for additional properties. ================================================ FILE: items/vest-asset.rst ================================================ .. _doc_item_asset_vest: Vest Assets =========== The ItemVestAsset class is used by clothing items occupying the "vest" slot. Vests can be worn by players and zombies, and cover their torso. Game Data File -------------- The ItemVestAsset class inherits properties from the :ref:`ItemBagAsset ` class. Properties that are required (or recommended) are listed in the table below. .. list-table:: :widths: 30 40 30 :header-rows: 1 * - Class - Property Name - Required Value * - :ref:`ItemAsset ` - :ref:`GUID ` - * - :ref:`ItemAsset ` - :ref:`ID ` - * - :ref:`ItemAsset ` - :ref:`Type ` - ``Vest`` * - :ref:`ItemAsset ` - :ref:`Useable ` - ``Clothing`` Properties `````````` Vests have no unique properties. Refer to parent classes for additional properties instead. ================================================ FILE: items/water-asset.rst ================================================ .. _doc_item_asset_water: Water Assets ============ Drinks are created from the ItemWaterAsset class. They are consumed by the player on use, and directly affect a player's stats such as water or stamina. This inherits the :ref:`ConsumeableAsset ` class. Item Asset Properties --------------------- **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Water``) **Useable** *enum* (``Consumeable``) **ID** *uint16*: Must be a unique identifier. Water Asset Properties ---------------------- Drinks have no unique asset properties. Refer to parent classes for additional properties. ================================================ FILE: items/weapon-asset.rst ================================================ .. _doc_item_asset_weapon: Weapon Assets ============= The ItemWeaponAsset class is a base class that other classes are derived from. This asset provides various properties related to damaging players, structures, and other entities – but its specific behavior depends on the child class being used. This inherits the :ref:`ItemAsset ` class. Weapon Asset Properties ----------------------- **Allow_Flesh_Fx** *bool*: Boolean for if special effects should occur when damaging flesh. Defaults to true. **Durability** *float32*: Probability of quality loss upon the weapon being used, as a decimal. .. _doc_item_asset_weapon:range: **Range** *float32*: The maximum distance in meters before damage is no longer possible. For ballistic projectile ranged weapons, this is the maximum distance a projectile may travel. For melee weapons, this is the maximum swinging distance. For physics projectile ranged weapons, this is the radius of the explosion. **Wear** *uint8*: Increment to degrade quality by. Defaults to 1. .. _doc_item_asset_weapon:player_damage: Player Damage ````````````` **Bypass_Allowed_To_Damage_Player** *bool*: Boolean for if the weapon should bypass the requirements for being allowed to damage other players. Typically, a weapon cannot damage another player if the server is set to PvE, or if the target player is a part of the same group and friendly fire is disabled. Defaults to false. **Player_Damage** *float32*: Amount of damage that should be dealt to player entities, prior to modifiers such as limb multipliers. **Player_Leg_Multiplier** *float32*: Multiplier on damage targeted against a player's legs. Limb multipliers are not utilized by explosive weapons. **Player_Arm_Multiplier** *float32*: Multiplier on damage targeted against a player's arms. Limb multipliers are not utilized by explosive weapons. **Player_Spine_Multiplier** *float32*: Multiplier on damage targeted against a player's torso. Limb multipliers are not utilized by explosive weapons. **Player_Skull_Multiplier** *float32*: Multiplier on damage targeted against a player's head. Limb multipliers are not utilized by explosive weapons. **Player_Damage_Bleeding** *enum* (``Always``, ``Default``, ``Heal``, ``Never``): Determines the effect the weapon has in relation to the "Bleeding" status effect. When using "Always", the Bleeding status effect will always be applied on hit. When using "Default", the Bleeding status effect will only be applied if the necessary damage threshold is met. When using "Heal", anyone hit by the weapon will have their Bleeding status effect removed. When using "Never", the Bleeding status effect is never applied by this weapon. Defaults to "Default" enumerator. **Player_Damage_Bones** *enum* (``Always``, ``Heal``, ``None``): Determines the effect the weapon has in relation to the "Broken Bones" status effect. When using "Always", the Broken Bones status effect will always be applied on hit. When using "Heal", anyone hit by the weapon will have their Broken Bones status effect removed. When using "Never", the Broken Bones status effect is never applied by this weapon. Defaults to the "None" enumerator. **Player_Damage_Food** *float32*: Amount of degradation dealt to a targeted player's food. Positive values are beneficial (increasing food level), and negative values are detrimental (decreasing food level). Negative values are blocked in the same situations damage is blocked (e.g., in safezones or shortly after respawns). **Player_Damage_Water** *float32*: Amount of degradation dealt to a targeted player's water. Positive values are beneficial (increasing water level), and negative values are detrimental (decreasing water level). Negative values are blocked in the same situations damage is blocked (e.g., in safezones or shortly after respawns). **Player_Damage_Virus** *float32*: Amount of degradation dealt to a targeted player's immunity. Positive values are beneficial (increasing immunity level), and negative values are detrimental (decreasing immunity level). Negative values are blocked in the same situations damage is blocked (e.g., in safezones or shortly after respawns). **Player_Damage_Hallucination** *float32*: Length of hallucinations inflicted onto a targeted player, in seconds. Positive values are detrimental (increasing hallucination duration), and negative values are beneficial (decreasing hallucination duration). Positive values are blocked in the same situations damage is blocked (e.g., in safezones or shortly after respawns). Zombie Damage ````````````` **Zombie_Damage** *float32*: Amount of damage that should be dealt to zombie entities, prior to modifiers such as limb multipliers. **Zombie_Leg_Multiplier** *float32*: Multiplier on damage targeted against a zombie's legs. Limb multipliers are not utilized by explosive weapons. **Zombie_Arm_Multiplier** *float32*: Multiplier on damage targeted against a zombie's arms. Limb multipliers are not utilized by explosive weapons. **Zombie_Spine_Multiplier** *float32*: Multiplier on damage targeted against a zombie's torso. Limb multipliers are not utilized by explosive weapons. **Zombie_Skull_Multiplier** *float32*: Multiplier on damage targeted against a zombie's head. Limb multipliers are not utilized by explosive weapons. **Stun_Zombie_Always** *flag*: Specified if a zombie should always be stunned when targeted by the weapon. **Stun_Zombie_Never** *flag*: Specified if a zombie should never be stunned when targeted by the weapon. **Zombie_Ragdoll_Force_Multiplier** *float32*: Scales force applied to zombie ragdoll. Defaults to 1. Animal Damage ````````````` **Animal_Damage** *float32*: Amount of damage that should be dealt to animal entities, prior to modifiers such as limb multipliers. **Animal_Leg_Multiplier** *float32*: Multiplier on damage targeted against a animal's limbs. Limb multipliers are not utilized by explosive weapons. **Animal_Spine_Multiplier** *float32*: Multiplier on damage targeted against a animal's torso. Limb multipliers are not utilized by explosive weapons. **Animal_Skull_Multiplier** *float32*: Multiplier on damage targeted against a animal's head. Limb multipliers are not utilized by explosive weapons. Construct Damage ```````````````` **BladeID** *uint8*: Weapon can damage any resources or objects that have a matching BladeID. Deprecated in favor of BladeIDs and BladeID\_#. **BladeIDs** *int32*: Total number of unique BladeID\_# values. **BladeID_#** *uint8*: Weapon can damage any resources or objects that have a matching BladeID\_# value. **Barricade_Damage** *float32*: Amount of damage that should be dealt to barricades, prior to modifiers. **Structure_Damage** *float32*: Amount of damage that should be dealt to structures, prior to modifiers. **Vehicle_Damage** *float32*: Amount of damage that should be dealt to vehicles, prior to modifiers. **Resource_Damage** *float32*: Amount of damage that should be dealt to resources, prior to modifiers. **Object_Damage** *float32*: Amount of damage that should be dealt to objects, prior to modifiers. Defaults to the value used by Resource_Damage. **Invulnerable** *flag*: Specified if damage should affect objects, structures, barricades, and vehicles that are considered invulnerable to low-power weaponry. Not applicable to explosive weapons, which will always ignore invulnerability. ================================================ FILE: make.bat ================================================ @ECHO OFF pushd %~dp0 REM Command file for Sphinx documentation if "%SPHINXBUILD%" == "" ( set SPHINXBUILD=sphinx-build ) set SOURCEDIR=. set BUILDDIR=_build if "%1" == "" goto help %SPHINXBUILD% >NUL 2>NUL if errorlevel 9009 ( echo. echo.The 'sphinx-build' command was not found. Make sure you have Sphinx echo.installed, then set the SPHINXBUILD environment variable to point echo.to the full path of the 'sphinx-build' executable. Alternatively you echo.may add the Sphinx directory to PATH. echo. echo.If you don't have Sphinx installed, grab it from echo.http://sphinx-doc.org/ exit /b 1 ) %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% goto end :help %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% :end popd ================================================ FILE: mapping/charts.rst ================================================ .. _doc_mapping_charts: Charts ====== The Charts.unity3d file determines the colors usable by a map's chart view. This file contains two 32 × 1 px textures: "Height_Strip" and "Layer_Strip". Height_Strip ------------ Height_Strip is used for topographical colors. The leftmost pixel (0, 0) is used for water. Other pixels are sampled based on the height of the terrain, going from the lowest potential point (1, 0) to the highest potential point (31, 0). .. note:: Objects can also be configured to sample from the "Water" pixel (0, 0) or the "Ground" pixel (20, 0) of the Height_Strip. Layer_Strip ----------- Layer_Strip is used when something obstructs the terrain, such as an object or tree. The pixel sampled depends on the type of obstruction. Objects can be configured to use a different part of the Layer_Strip than their default, with some pixels only being used by such objects. - (0, 0): Concrete roads wider than 8 meters use this pixel. Usable by objects. - (1, 0): Concrete roads where width is less than or equal to 8 meters use this pixel. Usable by objects. - (2, 0): Usable by objects. - (3, 0): Non-concrete roads. Usable by objects. - (4, 0): Usable by objects. - (14, 0): Resources. - (15, 0): Large-type objects. Usable by objects. - (16, 0): Medium-type objects. Usable by objects. ================================================ FILE: mapping/curated-maps.rst ================================================ .. _doc_mapping_curated: Curated Maps ============ .. warning:: This program is still evolving. Some of this information could change, especially once we begin to accept the first maps under this new program! Community-created maps that are officially linked from in-game are considered **Curated Maps**. Players can experience more high-quality content, and modders can earn money from their work while getting their creations highlighted. We have introduced a new Curation Program for 2025 and beyond. Creating maps is intended to be a fun and rewarding hobby, and our new program should be more accessible to creators. How does a map get accepted? ```````````````````````````` Our streamlined program starts with you simply publishing a map to the Steam Workshop. It looks something like this: #. | You publish a cool map on the Steam Workshop. #. | We reach out to authors of cool maps on the Steam Workshop. #. | Legal agreements (e.g. establishing revenue share between co-authors). #. | You make any changes necessary (if any). #. | We commission artists (or you create) the contents of store bundles released alongside the map. #. | Your curated map is added to the game. While creating your map, we recommend gathering feedback from other players! Maps can be accepted at any time after being published, so authors can create and revise content without much worry. Eligibility / Guidelines ------------------------ Several factors may influence our decisions when accepting new maps. First and foremost – curated maps should meet our guidelines (detailed further below). .. tip:: We encourage working on projects even if they would not ineligible for curation. Creating a variety of Workshop content creates a valuable portfolio for future curation attempts, and may still benefit from being featured. Although not every map should be curated, we often feature non-curated maps in blogposts. Some particularly high-quality maps have received revenue share from Stockpile bundles. Following these guidelines will significantly improve your eligibility: Include Custom Content `````````````````````` Maps should feel new and exciting to players. Although we may accept maps that primarily use vanilla assets, we strongly believe including some amount of custom content on new maps is important. This helps make each map feel unique. Consider creating new items, having a unique architecture style for your towns, incorporating our modding features in innovative ways, and exploring game mechanics in different ways. No Third-Party Content `````````````````````` All content on the map must be an official asset from the base game, or be a custom asset that was created by you. We cannot accept maps that use assets from other people's mods (including other curated maps). Our modding documentation can help you get started! Art Style ````````` Curated experiences should still look and feel like *Unturned*. Any custom content on the map should generally match the base game's art style (similar to preexisting curated maps). Human-like drawings such as faces and skulls should be blocky, similar to the in-game characters. This is a common source of revision requests from us. Quality Assurance ````````````````` * | **Asset Validation**: Running the game with the :ref:`-ValidateAssets ` command-line flag should not produce any warnings or errors. * | **English Text**: Having an English-speaking member of the mod team is recommended, and `MoltonMontro `_ has offered to help with English-related questions. Most importantly in this regard is proper punctuation and grammar: while native English speakers can easily read incorrect punctuation, it is very helpful for non-native readers. Ironically this paragraph probably has some punctuation errors. * | **Project Organization**: To prevent unintended assets from being exported into asset bundles, convention is to separate the project files into Sources and MasterBundle directories. Hawaii is split between a directory called "HawaiiMasterBundle" in the project root, and a Sources directory which contains all of the .blend, .mb, .xcf, .psd, .ai, etc files. When exporting the asset bundle this ensures only game files like .fbx and .prefab are included. * | **Asset Duplication**: If multiple objects share identical prefabs, or use vanilla content, asset bundle size can be improved by sharing the same prefabs. For an example of this refer to the vanilla notes using Bundle_Override_Path. * | **Water Reflections**: When using water volumes, only one should have planar reflections enabled. These reflections require rendering the world a second time for each enabled volume, and are some of the most performance expensive effects in the game. * | **Overlapping Navmeshes**: No bounds should overlap. Otherwise zombies will appear and disappear unexpectedly in multiplayer. * | **Visibility Overlay**: The visibility menu in the editor sums the mesh complexity in each region. Ideally there should only be a few red zones. * | **Item Icons**: Each item should have a proper icon in the inventory. One way to quickly preview the icon is to attach an orthographic camera in Unity. Content Appropriacy ```````````````````` Content should be what is typically considered "family-friendly". For example: - | Text should be devoid of harsh profanity (anything considered heavy or mild cursing, slurs, or strongly implied). Some alternatives to traditional profanity include nonsense words (such as *gosh*, *darn*, *dang*, *drats*, and *heck*), cut-off text, or redactions (e.g., *\[REDACTED]* or *\[UNINTELLIGIBLE]*). - | Explicit depictions of drugs, alcohol, and other substances is not allowed. Similar ideas with a looser association, such as berry mixes instead of alcohol; or things like vineyards, bottles, kegs, or distilleries; is allowed. Cigarettes, vaping, smoking, and tobacco are not allowed. - | Text should be gender-neutral. For example, "Firefighter" instead of "Fireman." - | Do not link to out-of-game content (for example, websites and phone numbers). We typically request phone numbers be changed to 555: https://en.wikipedia.org/wiki/555_(telephone_number) Menu Visibility --------------- One key component of sharing a curated map, trending popular workshop item, or specifically featured map is spotlighting it on the main menu. In any of these cases an article is placed above the recent news and announcements showcasing the preview image, and an expandable description. In-game the description supports the following BBCode tags: * ``[b]`` * ``[i]`` * ``[list]`` * ``[*]`` * ``[h1]`` * ``[img]`` * ``[url]`` Ideally descriptions are kept succinct, so separate discussion topics might be a better place for long sections like ID lists. By default popular items are surfaced, but workshop items can be specifically featured to help bring attention to projects with a lot of effort put into them, and curated maps. This can be done for new releases or major updates. Updates can link to a separate URL for the release notes. Additionally, curated maps are linked from the singleplayer curated maps list, and will inherit the main menu "new" or "updated" label. Stockpile Preparation --------------------- Each curated map release is usually accompanied by a few cosmetics and skins in the game's item store. Royalties from the sales are shared with the map author(s). **File Sharing**: Ideally, the items have been setup for use as clothes in-game, and then exported into a .unitypackage. This package will then be imported into the vanilla project. **Curated Workshop Item**: Payment splits are handled by a hidden curated workshop item. Setting this up usually takes a few weeks for new contributors' bank and tax information to be processed. **Bundles**: Two or three collections of sets with four to six items each. Bundles can either be a collection of loosely-related items, or a complete outfit. Outfit bundles should avoid having multiple items that take up the same cosmetic slot. **Mystery Boxes**: Fifteen to twenty items of rare, epic, or legendary rarity. The box can be themed, but all of the items should be usable individually – avoiding things like a set of matching shirts and pants that cannot be easily mixed with other cosmetic pieces. **Craftable Items**: Ten to twenty items of uncommon rarity. Unlike mystery box contents, it is far more appropriate for craftable items to have matching sets and simple recolors. FAQ --- **Q. Are any maps planned to release under the previous program?** Yes. There's several maps which predate this new program. We believe many of these will be released throughout 2025. **Q. When's the earliest we could see maps release under this new program?** Since there's already several curated maps releasing throughout this year, and some changes aren't ready for the new program yet, earliest would probably be end-of-year or sometime in 2026. **Q. Are there any upcoming changes to this program?** We're looking to revise the single-player map selection menu, and are considering additional ways players could support their favorite maps (e.g., a cosmetic that adds a small badge next to the player's name when they're playing on a specific map). This is all – to some extent – still subject to change. **Q. Do curated maps receive updates?** We may suggest some fixes or other adjustments necessary for the map to meet our expectations. However, additional content is largely left to the discretion of the map author(s). **Q. What game modes can maps be accepted for?** Maps designed for officially-supported modes (Survival, Arena) are the most likely to be accepted. We may occasionally consider some maps designed for popular custom game modes. **Q. Can multiple maps be released together?** If/when considering maps to release together, we'd like to ensure it makes sense to do so. For example, an arena map and a PvE-focused survival map. This is something we're still exploring. ================================================ FILE: mapping/editor-asset-redirectors.rst ================================================ .. _doc_mapping_redirectors: Editor Asset Redirectors ======================== **Editor Asset Redirectors** allow for quickly replacing objects, resources, materials, or foliage assets in bulk. Redirects apply while loading a map in the level editor. Any changes are then kept when saving the map. Create a file named "**EditorAssetRedirectors.txt**" in the Unturned folder. - Empty lines are ignored. - Lines starting with ``//`` or ``#`` are ignored. - Each redirect should include two :ref:`GUIDs ` separated by an arrow ``->``. For example: .. code-block:: text // Replace Boulder_00 with Boulder_01 6125b4de591b44359237f6d7191dd919 -> ee402fc9debe4f03bffb31a49eb04fb7 // Replace Maple_0 with Maple_3 63cb368c94b14000aabc5325b048cfa3 -> 011d1369cd56497488827b44509b0b4b ================================================ FILE: mapping/favorite-searches.rst ================================================ .. _doc_mapping_searches: Favorite Searches ================= The objects editor supports **Favorite Searches** which allows lists of objects to be quickly looked up. Entering "fv:xyz" in the search bar loads xyz.txt from the game folder, and will match any of the lines in the file. Empty lines and lines starting with "//" (comments) are ignored. The .txt file extension was chosen because it is the notepad default. For example this matches anything with "fire" in the name or Road Line Cap #1: .. code-block:: text // Fire related props Fire // Specific road prop Cap #1 Road Line Recursive usage of filters is supported, so multiple favorite searches can be nested, or other filter types e.g. "Tunnel mb:core" includes tunnels from the vanilla objects. ================================================ FILE: mapping/level-batching.rst ================================================ .. _doc_mapping_batching: Level Batching ============== This article is intended for map developers and explains how to maximize draw call batching. For background information on the purpose of batching: - `Optimizing draw calls (Unity docs) `_ - `Texture atlas (Wikipedia) `_ - `Static batching (Unity docs) `_ Enabling batching in your level ------------------------------- By default batching is disabled because some parts of the level may be incompatible (causing graphical bugs), the texture atlas might be too big, it might worsen performance, etc. Publishing your map with batching enabled is only recommended after double-checking each location in singleplayer. (batching is disabled in the level editor) You can test it by adding this property to your level's ``Config.json`` file: .. code-block:: json "Batching_Version": 2 The purpose of the version number is to allow future improvements without potentially breaking existing maps. For example, if atlas generation is supported for more shaders in an update it might behave unexpectedly, so those shaders would be excluded on older versions. Purpose of atlas generation --------------------------- Using fewer unique materials is almost always better for performance. Combining materials which only differ in their texture allows them to benefit from static and dynamic batching. If you want you can manually create a texture atlas for your own meshes, but resizing requires updating all your mesh UVs, and is generally a hassle. Considering that most workshop maps use objects from a variety of different mod packs, atlas generation helps them all work together. The maximum included texture size defaults to 128x128. Including bigger textures risks exceeding the maximum texture size, but can be adjusted with this option in the level config: .. code-block:: json "Batching_Max_Texture_Size": 256 Materials eligible for atlas inclusion -------------------------------------- Standard (Decalable) or Standard (Specular setup) (Decalable): - Mode is Opaque - Texture is unset, or is 128x128 or smaller with Clamp wrap mode - All other material features are default Custom/Card: supported for the automatically generated tree skybox models. Custom/Foliage: default trees/bushes. Excluding specific objects and resources from batching ------------------------------------------------------ If you know your asset is incompatible you can add this line to the .dat file: .. code-block:: unturneddat Exclude_From_Level_Batching true NPCs, decals, and speedtrees (when enabled) are excluded by default. This option may be useful for elaborate setups using Unity Event components. For example if an event moves the renderer transform or sets material parameters. Finding renderers that could benefit from atlas inclusion --------------------------------------------------------- By default the game considers every renderer in objects and resources. You can enable logging for why each renderer is excluded with the ``-LogLevelBatchingTextureAtlasExclusions`` launch option. Inclusion in the atlas is beneficial to merge as many meshes as possible into as few static batches as possible, but ineligible renderers will use static batching regardless. None of the messages logged are "errors" per se. It only explains why the game cannot (yet) atlas them. The most useful message for finding assets to modify is "Wrap Mode is not Clamp" because if the mesh does not require UVs outside the 0-1 square it can use ``Clamp`` wrap mode. Validating UVs -------------- When textures are merged into an atlas any meshes referencing them need their UV coordinates updated. If any UVs are outside the 0-1 square they will now be overlapping a completely different texture and appear incorrectly. You can use the ``-ValidateLevelBatchingUVs`` launch option to log any batched meshes with out-of-bounds UVs. For example this error with the vanilla chess board:: Mesh "Model_0" in renderer "Chess_0/Model_0" has UVs outside [0, 1] range (should be excluded from level batching) In the case of the chess board it was a mistake in the unwrapping which was then fixed, but in most cases this would suggest the mesh relies on ``Wrap Mode`` being ``Repeat``. Previewing renderers using atlas -------------------------------- You can visualize which renderers have been included in the texture atlas by loading singleplayer with the ``-PreviewLevelBatchingTextureAtlas`` launch option: .. figure:: img/TextureAtlasPreview.jpg Berlin with texture atlas preview enabled. All renderers in white were merged into a single material per shader. It is not necessarily bad that some materials were not merged. For example, the HVAC units on the rooftops in the screenshot all share a material already, so they are able to use static batching together. The same goes for the roads and overpass. Previewing renderers using static batching ------------------------------------------ You can visualize which mesh renderers are included in static batching by loading singleplayer with the ``-PreviewLevelBatchingUniqueMaterials`` launch option. Each unique material is assigned a random hue. The brightness of the color decreases in order of uniqueness. i.e., The brightest color is used by the most renderers, and the darkest color is used by only a few. ================================================ FILE: mapping/level-config.rst ================================================ .. _doc_mapping_config: Level Config ============ Each level is associated with an optional Config.json file. These files were originally added to make it easy to provide extra information about the level on the main menus, but grew over time to include gameplay parameters as well. In the future some of these might be moved to a more appropriate file like a level asset. Main Menus ---------- **Creators** *string[]*: Names in credits. **Collaborators** *string[]*: Names in credits. **Thanks** *string[]*: Names in credits. **CustomCredits**: Maps header internal title(s) to a list of names. The display title is formatted according to the level's localization file. For example: .. code-block:: json "CustomCredits": { "Music": [ "musician67", "SoundDesigner (these names aren't localized)" ], "Art": [ "MyFavouriteArtist" ] } .. note:: In that example, the keys ``Music`` and ``Art`` would be translated from the level's localization file. **Associated_Stockpile_Items** *int[]*: Economy itemdefids to feature on map screens. One is chosen at random each time the map is shown. Used by curated maps to link their items which have payment splits. **Feedback** *string*: URL to discussions. If not explicitly set, defaults to the workshop item's discussions page. **Visible_In_Matchmaking** *bool*: Should this map be listed in the matchmaking menu? Used to filter out test and demo maps. **Version** *string*: #.#.#.# format version number. Vanilla version numbers use 3.Year.Update.Patch, but that is optional. Incrementing the version number for every upload is good practice because: 1. When client and server files do not match it is more helpful to show a version number error message rather than a generic file mismatch error. 2. Searching by map in the server browser can filter servers running the same version of the map. **Tips** *int*: Number of Tip_# keys defined in level's localization files, if any. Overrides vanilla tip messages on the loading screen. **RequiredWorkshopFileIds** *ulong[]*: Dependency workshop file IDs. If these file(s) are not loaded then singleplayer and editor menus display a "Missing Dependencies" message and prevent entering the map. .. code-block:: json "RequiredWorkshopFileIds": [ 123456789, 123456789 ] Arena Mode ---------- **Use_Arena_Compactor** *bool*: Should circles be randomized periodically? **Arena_Loadouts**: Array of items to grant when spawning into arena. Each entry has a Table_ID spawn table to generate from, and an Amount number of times to grant from spawn table. For example: .. code-block:: json "Arena_Loadouts": [ { "Table_ID": 28007, "Amount": 1 }, { "Table_ID": 28008, "Amount": 1 } ] General ------- **Asset**: Object with GUID of :ref:`Level Asset ` to instantiate on this map. For example: .. code-block:: json "Asset": { "GUID": "12dc9fdbe9974022afd21158ad54b76a" } **Trains**: Array of train vehicles to spawn. Only one of each train asset can exist at a given time because the vehicle ID is used to match saved trains to tracks. Road index can be seen by selecting a road in the level editor. Placement is normalized between the start and end of the track length. For example: .. code-block:: json "Trains": [ { "VehicleID": 187, "RoadIndex": 0, "Min_Spawn_Placement": 0.1, "Max_Spawn_Placement": 0.9 } ] **Mode_Config_Overrides**: Pairs of server config properties and values to override them. For example: .. code-block:: json "Mode_Config_Overrides": { "Zombies.Min_Drops": 5, "Zombies.Max_Drops": 10, "Vehicles.Armor_Multiplier": 0.1, "Gameplay.Allow_Shoulder_Camera": false } Additionally, overrides can be applied per-difficulty with the ``EasyDifficulty_Config_Overrides``, ``NormalDifficulty_Config_Overrides``, and ``HardDifficulty_Config_Overrides`` properties. **Allow_Underwater_Features** *bool*: Should legacy details and navigation bounds be restricted underwater? **Terrain_Snow_Sparkle** *bool*: Should IS_SNOWING shader keyword be enabled? **Use_Legacy_Clip_Borders** *bool*: Should invisible walls matching map size be created? Defaults to true. **Use_Legacy_Ground** *bool*: Should default terrain be created? Alternative is to use landscape tiles. Defaults to true. **Use_Legacy_Water** *bool*: Should global water plane be enabled? Alternative is to use water volumes. Defaults to true. **Use_Vanilla_Bubbles** *bool*: Should vanilla water bubble effects be enabled? Defaults to true. **Use_Legacy_Snow_Height** *bool*: Should travelling vertically past snow height threshold enable snow effects? Defaults to true. **Use_Legacy_Oxygen_Height** *bool*: Should travelling vertically past a certain point deplete oxygen? Defaults to true. **Use_Rain_Volumes** *bool*: Should rain flag in ambiance volume be used? **Use_Snow_Volumes** *bool*: Should snow flag in ambiance volume be used? **Use_Underground_Whitelist** *bool*: Should underground players not inside a whitelist volume be teleported to the terrain surface? Useful to curb out-of-bounds exploits. **Is_Aurora_Borealis_Visible** *bool*: Should aurora borealis effects be enabled? **Snow_Affects_Temperature** *bool*: Should snow inflict cold damage? **Weather_Override** *ELevelWeatherOverride*: Can be set to rain or snow to lock weather type. **Has_Global_Electricity** *bool*: Should all powerable items and objects have power by default? **Gravity** *float*: Acceleration of gravity. Defaults to -9.81. **Blimp_Altitude** *float*: Height override for blimp buoyancy. Defaults to 150. **Max_Walkable_Slope** *float*: Steepest ground angle players can walk without sliding. Defaults to 59. **Prevent_Building_Near_Spawnpoint_Radius** *float*: Closest distance players can build to spawn points. Useful to override for close-quarters maps. Defaults to 16. **Spawn_Loadouts**: Array of items to grant when spawning in any mode. Refer to ``Arena_Loadouts``. **Allow_Holiday_Redirects** *bool*: Whether certain assets like objects, trees and landscapes should load alternative versions during holiday events. **Enable_Clutter_Option** *bool*: If true, "Load Clutter" graphics option is supported on this map. Defaults to false. This is opt-in so that the map creator(s) can decide whether the removed details are an acceptable compromise. **Batching_Version** *int*: Please refer to :ref:`doc_mapping_batching`. **Batching_Max_Texture_Size** *int*: Overrides the maximum texture size included in the :ref:`doc_mapping_batching` atlas. Please keep in mind that including bigger textures risks exceeding the maximum texture size. HUD --- Disable various elements of the heads-up display. **PlayerUI_HealthVisible** *bool* **PlayerUI_FoodVisible** *bool* **PlayerUI_WaterVisible** *bool* **PlayerUI_VirusVisible** *bool* **PlayerUI_StaminaVisible** *bool* **PlayerUI_OxygenVisible** *bool* **PlayerUI_GunVisible** *bool* **Allow_Crafting** *bool* **Allow_Skills** *bool* **Allow_Information** *bool* Deprecated ---------- **Can_Use_Bundles** *bool*: Used in the past for timed curated maps to disable using their assets in the level editor which could break after moving the map from the vanilla content to the workshop. **Category** *ESingleplayerMapCategory*: Mostly automated now. Can be set to Misc to explicitly show in the miscellaneous map category. **Has_Atmosphere** *bool*: If false, disable stars in skybox. **Has_Discord_Rich_Presence** *bool*: Only valid for official maps. If discord integration is enabled and this flag is true discord will check for a map icon configured in their partner page. **Item** *int*: Kept for backwards compatibility. Ignored if ``Associated_Stockpile_Items`` are set. **Load_From_Resources** *bool*: Used in the past for curated maps with assets in the vanilla Resources/Bundles/* directory. Master Bundles completely replaced this. **Should_Verify_Objects_Hash** *bool*: With the newer asset integrity checks this is obsolete because each object/tree used in the level is checked with the server, and ignored if the server is missing the asset. Trees.dat and Objects.dat can always be included because missing assets do not factor into those hashes anymore. **Use_Legacy_Fog_Height** *bool*: Should default terrain height be used for fog falloff? If false, devkit landscape tile limits are used instead. Defaults to true. **Use_Legacy_Objects** *bool*: Should objects be loaded from Objects.dat file? Devkit objects were moved into this file, so this option no longer has any effect. ================================================ FILE: mapping/manual-object-culling.rst ================================================ .. _doc_mapping_culling: Manual Object Culling ===================== This article is intended for map developers and explains **Manual Object Culling** volumes. Drawing fewer objects is usually better for performance. Culling volumes allow you to override the distance at which the contained objects are drawn where otherwise they might be drawn much further away than necessary. For example, by default the vanilla chair models are visible from quite far away in case they are placed outdoors, whereas inside an office building they only need to be seen while near the building. .. figure:: img/CullingVolumes.jpg A building in Moscow with culling volumes. This comes with an obvious downside: when zooming in on most buildings it is readily apparent that the furniture is missing. I experimented with some workarounds like enabling objects near the center of your view while zoomed, but it did not feel any better. In my opinion the performance trade-off is worth it. "Large" objects like shipping containers that have higher gameplay importance as cover are excluded by default, and most buildings have their culling volumes inset from the edges slightly so that objects in the windows are excluded. Editing volumes --------------- You can enable the **Preview Culling** checkbox to hide all objects inside culling volumes. This is useful to find any objects that are not included when they should be. For example, while working on this update I realized the volumes in the vanilla cargo ships did not extend low enough to catch some of the furniture in the crew quarters. Objects inside volumes are found when loading the level. While working in the editor you can click **Refresh Objects** to re-find all objects/volumes on the map. Updating the culling volumes costs some performance, so a large number of small volumes may actually make performance worse. It is worth comparing though. Excluding specific objects -------------------------- If you know your asset should never be managed by culling volumes you can add this line to the .dat file: .. code-block:: unturneddat Exclude_From_Culling_Volumes true For example, the aerospace facility on Germany is excluded so that the manually placed culling volumes can hide large objects like shipping containers without accidentally hiding the giant structure. Note: volumes owned by objects automatically exclude their owner object. Volumes owned by objects ------------------------ Most vanilla buildings come with default culling volumes which are not selectable because they are not saved in the level. These are the precursor to the manually placeable culling volumes, and have been invisibly hiding objects since 2014! Part of the goal with the culling volumes was to finally make these viewable in the editor because they have caused a lot of confusion over the years, especially for modded objects created without knowing they were there. This is an area for future improvement, so I would not necessary recommend for/against adding them to your own objects. The following options are very old and poorly named, but can be specified in your object's .dat file to automatically create a culling volume: **LOD** *enum*: Can be set to ``Mesh`` or ``Area``. ``Mesh`` uses the bounds of renderers, and ``Area`` uses the size of Occlusion Area components. Note the Occlusion Area component's do not have any special functionality. At the time it was a workaround to allow placement in Unity with an otherwise unused component. **LOD_Bias** *float*: Multiplier for the default 64m culling distance. For example, 2 would be visible up to 128m. **LOD_Center_X, LOD_Center_Y, LOD_Center_Z** *float*: Offsets volume position relative to object transform along each axis. **LOD_Size_X, LOD_Size_Y, LOD_Size_Z** *float*: Offsets calculated volume size in Mesh mode. Many vanilla buildings with flat rooftops use a negative Z offset to exclude HVAC units placed on the roof. Testing culling volume performance benefit ------------------------------------------ If you would like to check whether culling volumes are providing any benefit you can run the game with the ``-DisableCullingVolumes`` launch option. Dense areas like Seattle tend to have the most noticeable difference. ================================================ FILE: npcs/conditions.rst ================================================ .. _doc_npc_asset_conditions: Conditions ========== Conditions can be held by NPCs, interactable objects, and item blueprints. Each grouping of conditions is called a **conditions list** and starts with the ``Conditions`` property. Properties in a conditions list are named in the format of ``ConditionPrefix_#_PropertyName``. For most conditions lists the prefix is ``Condition``, such as ``Condition_#_Type``. This is not always the case, such as for :ref:`blueprints ` which use ``Blueprint_#_Conditions``. **Conditions** *byte*: Total number of conditions. There should be a number of ``Condition_#_Type`` properties equal to this value. **Condition_#_Type** *enum* (``Compare_Flags``, ``Date_Counter``, ``Flag_Bool``, ``Flag_Short``, ``Currency``, ``Experience``, ``Item``, ``Kills_Animal``, ``Kills_Horde``, ``Kills_Object``, ``Kills_Player``, ``Kills_Tree``, ``Kills_Zombie``, ``Player_Life_Food``, ``Player_Life_Health``, ``Player_Life_Stamina``, ``Player_Life_Virus``, ``Player_Life_Water``, ``Quest``, ``Reputation``, ``Skillset``, ``Holiday``, ``Time_Of_Day``, ``Volume_Overlap``, ``Weather_Blend_Alpha``, ``Weather_Status``): Specify the type of condition. Like other indexed properties, indicing starts at ``0``. **Condition_#_Reset** *flag*: Set back to equivalent of 0 when completed. **Condition_#_Logic** *enum* (``Less_Than``, ``Less_Than_Or_Equal_To``, ``Equal``, ``Not_Equal``, ``Greater_Than_Or_Equal_To``, ``Greater_Than``): Compare current state to target state. **Condition_#_UI_Requirements** *string*: Comma-separated condition indices. If set, only show this condition in the UI when the conditions with these indices are met. For example, a condition with "1, 2" will only be shown when conditions 1 and 2 have been completed. Flags ----- Compare_Flags ````````````` Compare left-hand flag A, to right-hand flag B. **Condition_#_Type** *enum* (``Compare_Flags``) **Condition_#_A_ID** *uint16*: Left-hand flag ID. **Condition_#_Allow_A_Unset** *bool*: Pass condition flag onto player, if they do not have the flag already. **Condition_#_B_ID** *uint16*: Right-hand flag ID. **Condition_#_Allow_B_Unset** *bool*: Pass condition if player does not have the flag yet. Date_Counter ```````````` Every in-game morning, the world's "date counter" is incremented. In a fresh save it starts at zero. This condition takes the remainder of the date counter divided by ``Divisor`` and compares it with ``Value`` according to ``Logic``. For example, an in-game event can be configured to occur every 4th and 5th day by setting ``Divisor`` to 5, ``Value`` to 3, and ``Logic`` to ``Greater_Than_Or_Equal_To``. **Condition_#_Type** *enum* (``Date_Counter``) **Condition_#_Value** *int64*: Number to compare the remainder with. **Condition_#_Divisor** *int64*: Number to divide the world date counter by. Flag_Bool ````````` Boolean flag condition. **Condition_#_Type** *enum* (``Flag_Bool``) **Condition_#_ID** *uint16*: ID of flag to check. **Condition_#_Value** *bool*: Target value, as a boolean. **Condition_#_Allow_Unset** *flag*: Pass condition if player does not have the flag yet. Flag_Short `````````` Short flag condition. **Condition_#_Type** *enum* (``Flag_Short``) **Condition_#_ID** *uint16*: ID of flag to check. **Condition_#_Value** *int16*: Target value for the flag, as a 16-bit signed integer. **Condition_#_Allow_Unset** *flag*: Pass condition if player does not have the flag yet. Player ------ Currency ```````` Refer to :ref:`Currency ` documentation. **Condition_#_Type** *enum* (``Currency``) **Condition_#_GUID** *string*: GUID of currency asset. **Condition_#_Value** *int*: Target value, in terms of currency. Experience `````````` **Condition_#_Type** *enum* (``Experience``) **Condition_#_Value** *int*: Target value, in terms of experience. Item ```` **Condition_#_Type** *enum* (``Item``) **Condition_#_ID** *uint16*: ID of item to search player's inventory for. **Condition_#_Amount** *int*: Quantity of the item required. Kills_Animal ```````````` **Condition_#_Type** *enum* (``Kills_Animal``) **Condition_#_ID** *uint16*: ID of short flag to track stat. **Condition_#_Value** *int*: Target value, in terms of animal kills. **Condition_#_Animal** *uint16*: ID of animal required. Kills_Horde ``````````` **Condition_#_Type** *enum* (``Kills_Horde``) **Condition_#_ID** *uint16*: ID of short flag to track stat. **Condition_#_Value** *int*: Target value, in terms of beacons completed. **Condition_#_Nav** *byte*: Index of the navmesh that beacons should be completed in, seen as visible in the level editor. Kills_Object ```````````` **Condition_#_Type** *enum* (``Kills_Object``) **Condition_#_ID** *uint16*: ID of short flag to track stat. **Condition_#_Value** *int*: Target value, in terms of object destructions. **Condition_#_Object** *string*: GUID of object required. **Condition_#_Nav** *byte*: Index of the navmesh that objects should be destroyed in, seen as visible in the level editor. Kills_Player ```````````` **Condition_#_Type** *enum* (``Kills_Player``) **Condition_#_ID** *uint16*: ID of short flag to track stat. **Condition_#_Value** *int*: Target value, in terms of player kills. Kills_Tree `````````` **Condition_#_Type** *enum* (``Kills_Tree``) **Condition_#_ID** *uint16*: ID of short flag to track stat. **Condition_#_Value** *int*: Target value, in terms of resource destructions. **Condition_#_Tree** *string*: GUID of resource required. Kills_Zombie ```````````` **Condition_#_Type** *enum* (``Kills_Zombie``) **Condition_#_ID** *uint16*: ID of short flag to track stat. **Condition_#_Value** *int*: Target value, in terms of zombies killed. **Condition_#_Zombie** *enum* (``Acid``, ``Boss_All``, ``Boss_Electric``, ``Boss_Elver_Stomper``, ``Boss_Fire``, ``Boss_Magma``, ``Boss_Nuclear``, ``Boss_Spirit``, ``Boss_Wind``, ``Burner``, ``Crawler``, ``DL_Blue_Volatile``, ``DL_Red_Volatile``, ``Flanker_Friendly``, ``Flanker_Stalk``, ``Mega``, ``None``, ``Normal``, ``Spirit``, ``Sprinter``): Type of zombie required. **Condition_#_Spawn_Quantity** *int*: Number of zombies to spawn. Defaults to 1. **Condition_#_Nav** *byte*: Index of the navmesh that zombies should be killed in, seen as visible in the level editor. **Condition_#_Radius** *float*: Radius around players that zombies should be killed within, in meters. When a navmesh is unset and a radius is not specified, the radius defaults to 512 meters and is used for the condition. **Condition_#_MinRadius** *float*: Zombies must be killed at least this many meters away from the player. **Condition_#_Spawn** *flag*: Specified if the zombie type should be forcefully generated upon entering the area, which will then be deleted upon leaving the area. **Condition_#_LevelTableOverride** *int*: Unique ID of a zombie type shown in the level editor. If set, the zombie spawned will use that type. Defaults to -1. Player_Life_Food ```````````````` **Condition_#_Type** *enum* (``Player_Life_Food``) **Condition_#_Value** *int*: Target value, in terms of the player's current food. Player_Life_Health `````````````````` **Condition_#_Type** *enum* (``Player_Life_Health``) **Condition_#_Value** *int*: Target value, in terms of the player's current health. Player_Life_Stamina ``````````````````` **Condition_#_Type** *enum* (``Player_Life_Stamina``) **Condition_#_Value** *int*: Target value, in terms of the player's current stamina/energy. Player_Life_Virus ````````````````` **Condition_#_Type** *enum* (``Player_Life_Virus``) **Condition_#_Value** *int*: Target value, in terms of the player's current immunity. Player_Life_Water ````````````````` **Condition_#_Type** *enum* (``Player_Life_Water``) **Condition_#_Value** *int*: Target value, in terms of the player's current water. Quest ````` **Condition_#_Type** *enum* (``Quest``) **Condition_#_ID** *uint16*: ID of quest to check for. **Condition_#_Status** *enum* (``None``, ``Active``, ``Ready``, ``Completed``): Current state of the quest. **Condition_#_Ignore_NPC** *flag*: Player does not need to be talking to an NPC within 20 meters for the quest to be completable and turned in. Reputation `````````` **Condition_#_Type** *enum* (``Reputation``) **Condition_#_Value** *int*: Target value, in terms of reputation. Skillset ```````` **Condition_#_Type** *enum* (``Skillset``) **Condition_#_Value** *enum* (``Army``, ``Camp``, ``Chef``, ``Farm``, ``Fire``, ``Fish``, ``Medic``, ``None``, ``Police``, ``Thief``, ``Work``): Target value, as the skillset. For example, this condition could be used to offer unique questlines, dialogue, or blueprints depending on the player's chosen skillset. World ----- Holiday ``````` **Condition_#_Type** *enum* (``Holiday``) **Condition_#_Value** *enum* (:ref:`ENPCHoliday `): Target value, as the holiday. Is_Full_Moon ```````````` **Condition_#_Type** *enum* (``Is_Full_Moon``) **Condition_#_Value** *bool*: If true the condition passes when the full moon is up, otherwise if false the condition passes when the full moon is **not** up. Time_Of_Day ``````````` **Condition_#_Type** *enum* (``Time_Of_Day``) **Condition_#_Second** *int*: Second of a 24-hour clock (military time) to compare against. For example: ``0`` is midnight (the start of a day), ``43200`` is noon (12 o'clock), and ``86400`` is midnight (the end of a day). This condition respects the map's configured "Bias" values, as well as the day/night cycle length of the world. As a visual reference, the `Clock `_ item can be used. Volume_Overlap `````````````` **Condition_#_Type** *enum* (``Volume_Overlap``) **Condition_#_VolumeID** *string*: ID of volume(s) placed in the level editor to test. **Condition_#_PlayerCount** *int*: Target number of players in matching volumes to compare against. Volumes with identical IDs are grouped together. Weather_Blend_Alpha ``````````````````` The weather blend alpha condition compares the current intensity to a target value. For example, an NPC could sell umbrellas while rain is greater than 50% (0.5) blended in. This condition is supported by visibility, but is more expensive for visibility than the state condition because each listening object is updated when the intensity changes by 1% (0.01). **Condition_#_Type** *enum* (``Weather_Blend_Alpha``) **Condition_#_GUID** *string*: GUID of weather required. **Condition_#_Value** *float* [0, 1]: Target value, as the weather intensity blend. Weather_Status `````````````` The weather status condition tests the state of the global weather. This condition is supported by visibility. **Condition_#_Type** *enum* (``Weather_Status``) **Condition_#_GUID** *string*: GUID of weather required. **Condition_#_Value** *enum* (``Active``, ``Fully_Transitioned_In``, ``Fully_Transitioned_Out``, ``Transitioning``, ``Transitioning_In``, ``Transitioning_Out``): Target value, as the weather status. Localization ------------ **Condition_#**: Name of the condition as it appears in user interfaces. ================================================ FILE: npcs/currency-asset.rst ================================================ .. _doc_assets_currency: Currency Assets =============== Any collection of items with different numeric values can be associated together in a **Currency** asset. NPCs can then automatically convert between the different items, and vendor menus can display information using the linked currency. This is intended to be useful beyond real-world currencies, e.g. bartering ammunition. .. figure:: /img/VendorCurrency.jpg P.Riso's Hot Stuff vendor. Asset Setup ----------- The currency asset defines how numbers are formatted, which items make up the currency, and their individual values. An example can be found at Bundles/Items/Supplies/CanadianCurrency.asset. **Type** *string*: ``SDG.Unturned.CurrencyAsset`` **ValueFormat** *string*: String to format numeric value into. For example "${0:N0} CAD" is the vanilla Canadian currency format. **DefaultConditionFormat** *string*: If an NPC currency condition does not specify a formatting string this is used as the default. {0} is the total value held in the player's inventory, and {1} is the condition value. For example "${0:N0}/{1:N0} CAD" is the vanilla Canadian currency format. **Entries**: Array of items in the currency. Each has an **Item** GUID and **Value** integer. Optionally **Is_Visible_In_Vendor_Menu** bool can be false to hide the item from the NPC vendor currency list. For example these are the $10 and $20 notes in the Canadian currency: .. code-block:: unturnedasset { "Item" { "GUID" "b6b87dfad5f342dc91bbb2de950f56ee" } "Value" "10" } { "Item" { "GUID" "3b9847bb328d445495b64be9e5ea9400" } "Value" "20" } To link a vendor with a currency set the vendor asset's **Currency** to the currency asset's GUID. Vendors display all of the items sorted from lowest to highest value. NPC Logic --------- Conditions can use the **Currency** type to require different total amounts in the player's inventory. Rewards can use the **Currency** type as well to grant amounts. Refer to :ref:`Conditions ` documentation and :ref:`Rewards ` documentation for documentation. Testing ------- The built-in "give" command accepts currency GUIDs as an alternative to item IDs. For example the following grants $1,000 CAD to the local player: .. code-block:: shell /give 5150ca8f765d4a68bfe54912146da410/1000 ================================================ FILE: npcs/dialogue-asset.rst ================================================ .. _doc_npc_asset_dialogue: Dialogue Assets =============== **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Dialogue``) **ID** *uint16*: Must be a unique identifier. Values less than 2,000 are reserved for official content. .. tip:: To quickly test a specific dialogue, you can use the ``/dialogue guid`` command. This opens the dialogue as if your character were an NPC. Messages -------- Properties pertaining to dialogue performed by the NPC. Dialogue can utilize conditions and rewards. Messages that meet all of their conditions will be shown, and can grant rewards when the message is shown. These are prefixed with ``Message_#_``. For example, ``Message_0_Condition_0_Type Flag_Bool``. For more information, refer to the documentation for :ref:`Conditions ` and :ref:`Rewards ` respectively. **Messages** *int32*: Total number of possible messages. **Message_#_Pages** *byte*: Total number of pages the message has. **Message_#_Responses** *byte*: Total number of responses to be shown when this message is shown. If 0, then all messages are automatically a candidate to be shown. Defaults to 0. **Message_#_Response_#** *byte*: Index of the response to show. **Message_#_Prev** *uint16* or *GUID*: ID or GUID of dialogue to return to if there are no responses available for this message. Defaults to 0. **Message_#_FaceOverride** *byte*: Optional index of face image to use when this message is opened. Face is reset to character's default when unspecified or when dialogue is closed. Responses --------- Properties pertaining to dialogue available to the player. Dialogue can utilize conditions and rewards. Responses are only visible when conditions are met, and can grant rewards when selected. These are prefixed with ``Response_#_``. For example, `Response_0_Reward_0_Type Quest`. For more information, refer to the documentation for :ref:`Conditions ` and :ref:`Rewards ` respectively. **Responses** *byte*: Total number of possible responses. **Response_#_Messages** *byte*: Total number of messages to only show this response for. If 0, then it is shown for all messages. Defaults to 0. **Response_#_Message_#** *uint16*: Index of the message to show for. **Response_#_Dialogue** *uint16* or *GUID*: ID or GUID of the dialogue to open when selected. **Response_#_Quest** *uint16* or *GUID*: ID or GUID of the quest to preview when selected. **Response_#_Vendor** *uint16* or *GUID*: ID or GUID of the vendor to open when selected. Localization ------------ **Message_#_Page_#** :ref:`doc_data_richtext`: Text shown for the corresponding message page. **Response_#** :ref:`doc_data_richtext`: Text shown for the corresponding response option. ================================================ FILE: npcs/introduction.rst ================================================ .. _doc_npc_asset_intro: Introduction to NPCs ==================== Modders can create interactable NPC characters, with a customized appearance. A dialogue box can be made to appear to the player when interacted with, which can display potential responses that can chain into more dialogue options. Dialogue can lead to special interactions, such as quests or vendors. Additionally, NPC interactions can have a set of conditions that dictate what is available to the player, and rewards for performing various actions such as turning in a quest. Localization ------------ There are additional text formatting features available for NPC localization files. **\\**: Use a rarity color as the font color. Valid rarities are: ``common``, ``uncommon``, ``rare``, ``epic``, ``legendary``, ``mythical``, ``gold``, ``red``, ``orange``, ``yellow``, ``green``, ``blue``, and ``purple``. Alternatively, specify a six-digit hexadecimal number representing RGB color. **\**: Insert the NPC character's name. **\**: Insert the player character's name. **\**: New line. **\**: Pause dialogue for 0.5 seconds before continuing. ================================================ FILE: npcs/npc-asset.rst ================================================ .. _doc_object_asset_npc: NPC Character Assets ==================== **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``NPC``) **ID** *uint16*: Must be a unique identifier. **PlayerKnowsNameFlagID** *uint16*: If non-zero, NPC name is shown as ??? until bool flag is true. For example if set to 20 the NPC name is ??? until a Flag_Bool reward with ID 20 is set to true. Clothing -------- **Shirt** *uint16* or *GUID*: ID or GUID of shirt to wear. **Pants** *uint16* or *GUID*: ID or GUID of pants to wear. **Hat** *uint16* or *GUID*: ID or GUID of hat to wear. **Backpack** *uint16* or *GUID*: ID or GUID of backpack to wear. **Vest** *uint16* or *GUID*: ID or GUID of vest to wear. **Mask** *uint16* or *GUID*: ID or GUID of mask to wear. **Glasses** *uint16* or *GUID*: ID or GUID of glasses to wear. Holiday outfits ``````````````` NPC characters can have event-specific outfits, which will only appear during the assigned seasonal event. **Has_Halloween_Outfit** *flag*: Specified if event-specific clothing should be worn during the Halloween event. **Halloween_Shirt** *uint16* or *GUID*: ID or GUID of shirt to wear during the Halloween event. **Halloween_Pants** *uint16* or *GUID*: ID or GUID of pants to wear during the Halloween event. **Halloween_Hat** *uint16* or *GUID*: ID or GUID of hat to wear during the Halloween event. **Halloween_Backpack** *uint16* or *GUID*: ID or GUID of backpack to wear during the Halloween event. **Halloween_Vest** *uint16* or *GUID*: ID or GUID of vest to wear during the Halloween event. **Halloween_Mask** *uint16* or *GUID*: ID or GUID of mask to wear during the Halloween event. **Halloween_Glasses** *uint16* or *GUID*: ID or GUID of glasses to wear during the Halloween event. **Has_Christmas_Outfit** *flag*: Specified if event-specific clothing should be worn during the Festive event. **Christmas_Shirt** *uint16* or *GUID*: ID or GUID of shirt to wear. **Christmas_Pants** *uint16* or *GUID*: ID or GUID of pants to wear. **Christmas_Hat** *uint16* or *GUID*: ID or GUID of hat to wear. **Christmas_Backpack** *uint16* or *GUID*: ID or GUID of backpack to wear. **Christmas_Vest** *uint16* or *GUID*: ID or GUID of vest to wear. **Christmas_Mask** *uint16* or *GUID*: ID or GUID of mask to wear. **Christmas_Glasses** *uint16* or *GUID*: ID or GUID of glasses to wear. Appearance ---------- While in the Appearance menu in-game, modders can press Page Down to copy the player's current appearance to clipboard. **Face** *int*: Index of face image. **Hair** *int*: Index of hair mesh. **Beard** *int*: Index of beard mesh. **Color_Skin** *hex triplet*: Six-digit hexadecimal number representing RGB color. **Color_Hair** *hex triplet*: Six-digit hexadecimal number representing RGB color. **Backward** *flag*: Specified if character is left-handed. Pose ---- **Primary** *uint16* or *GUID*: ID or GUID of the weapon carried on the character's back, parallel to the spine. **Secondary** *uint16* or *GUID*: ID or GUID of the weapon carried on the character's hip, perpendicular to the spine. **Tertiary** *uint16* or *GUID*: ID or GUID of a non-weapon item to carry. **Equipped** *enum* (``Primary``, ``Secondary``, ``Tertiary``): The item in the specified slot will be held in the character's hands, rather than carried. **Dialogue** *uint16* or *GUID*: ID or GUID of the dialogue asset to open when interacted with. **Pose** *enum* (``Asleep``, ``Crouch``, ``Passive``, ``Prone``, ``Rest``, ``Sit``, ``Stand``, ``Surrender``, ``Under_Arrest``): Idle animation. **Pose_Head_Offset** *float*: Offset of the NPC's head from their body, in meters. Positive numbers offset it forward, while negative numbers offset it backward. Defaults to 0.1. **Pose_Lean** *float*: How far the NPC leans left or right, as a number from -1 to 1. Positive numbers learn to the NPC's left, while negative numbers lean to the NPC's right. Defaults to 0. **Pose_Pitch** *float*: How far the NPC leans forward or backward, in degrees. Numbers greater than 90 lean forward, while numbers less than 90 lean backward. Defaults to 90. Conditions ---------- An NPC character can be made to only appear while certain :ref:`conditions ` are met by the player. Localization ------------ **Name** *string*: Object name in level editors. **Character** *string*: Character name displayed when interacted with. ================================================ FILE: npcs/quest-asset.rst ================================================ .. _doc_npc_asset_quest: Quest Assets ============ **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Quest``) **ID** *uint16*: Must be a unique identifier. Conditions and Rewards ---------------------- Quests can be turned in when conditions are met, and players can receive rewards for turning quests in. For more information, refer to the documentation for :ref:`Conditions ` and :ref:`Rewards ` respectively. Quests have two types of rewards lists: 1. ``Rewards`` are granted when the quest is completed. 2. ``AbandonmentRewards`` are granted when the quest is removed without completing it. These are not granted when the player finishes the quest normally. Localization ------------ **Name** *string*: Quest name in user interfaces. **Description** :ref:`doc_data_richtext`: Quest description in user interfaces. ================================================ FILE: npcs/rewards-list-asset.rst ================================================ .. _doc_npc_asset_rewards_list: Rewards List Assets =================== **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``RewardsList``) The ``Rewards_List_Asset`` NPC reward type can either grant a rewards list asset directly, or a :ref:`Spawn Table Asset ` which resolves to the final asset. This could be used, for example, to randomly select one of several rewards list assets which then grants the player a gun along with related ammo items. A `Rewards List Volume` placed in the level editor can also reference a rewards list asset, and will grant the rewards if the conditions are met when a player enters the volume. Conditions must be met to grant the rewards. For more information, refer to the documentation for :ref:`Conditions ` and :ref:`Rewards ` respectively. Tip: you can use the ``/RunRewardList (guid)`` admin command to test a reward list in-game. ================================================ FILE: npcs/rewards.rst ================================================ .. _doc_npc_asset_rewards: Rewards ======= **Rewards** can be granted by NPCs, objects, and items. Each grouping of rewards is called a **rewards list** and starts with the ``Rewards`` property. Properties in a rewards list are named in the format of ``RewardPrefix_#_PropertyName``. For most rewards lists the prefix is ``Reward``, such as ``Reward_#_Type``. This is not always the case, such as with :ref:`quests ` which have two separate rewards lists named ``Rewards`` and ``AbandonmentRewards``, or consumables which use ``Quest_Rewards``. **Rewards** *byte*: Total number of rewards in the rewards list. There should be a number of ``Reward_#_Type`` properties equal to this value. **Reward_#_Type** *enum* (``Airdrop``, ``Flag_Bool``, ``Flag_Math``, ``Flag_Short``, ``Flag_Short_Random``, ``Achievement``, ``Currency``, ``Cutscene_Mode``, ``Effect``, ``Event``, ``Experience``, ``Item``, ``Item_Random``, ``Hint``, ``Player_Life_Food``, ``Player_Life_Health``, ``Player_Life_Stamina``, ``Player_Life_Virus``, ``Player_Life_Water``, ``Player_Spawnpoint``, ``Quest``, ``Reputation``, ``Rewards_List_Asset``, ``Teleport``, ``Vehicle``, ``Zombie``, ``Remove_Zombies``): Specify the type of reward. Like other indexed properties, indicing starts at ``0``. **Reward_#_GrantDelaySeconds** *float*: If set, the reward will be queued for the specified number of seconds before being granted to the player. Defaults to -1. **Reward_#_GrantDelayApplyWhenInterrupted** *bool*: If true, the reward will be granted when the player dies or disconnects. Defaults to false, in which case when the player dies any pending rewards are cancelled. Flags ----- Flag_Bool ````````` **Reward_#_Type** *enum* (``Flag_Bool``) **Reward_#_ID** *uint16*: ID of flag to set. **Reward_#_Value** *bool*: Set flag to Boolean value, of either "True" or "False". Flag_Math ````````` **Reward_#_Type** *enum* (``Flag_Math``) **Reward_#_A_ID** *uint16*: ID of flag to apply math to. **Reward_#_B_ID** *uint16*: ID of flag containing value to be applied mathematically. If not specified then ``B_Value`` is used instead. **Reward_#_B_Value** *int16*: default value to be applied mathematically if flag B has not been set on the player or if ``B_ID`` is zero. **Reward_#_Operation** *enum* (``Addition``, ``Assign``, ``Division``, ``Modulo``, ``Multiplication``, ``Subtraction``, ``Random_Inclusive``, ``Random_Exclusive``): For example, using the Addition operation would set A to the value of A + B. ``Random_Inclusive`` operation: Set flag A to random number between the value of A and B. For example if A is 1 and B is 3 the random number could be 1, 2, or 3. ``Random_Exclusive`` operation: Set flag A to random number between the value of A and B, excluding B. For example if A is 1 and B is 3 the random number could be 1 or 2. If the value of A and B are the same then the exclusion rule is ignored. Flag_Short `````````` **Reward_#_Type** *enum* (``Flag_Short``) **Reward_#_ID** *uint16*: ID of flag to modify. **Reward_#_Value** *int16*: Modify flag's current value with this short value. **Reward_#_Modification** *enum* (``Assign``, ``Decrement``, ``Increment``): Set value, subtract value, or add value. Flag_Short_Random ````````````````` **Reward_#_Type** *enum* (``Flag_Short_Random``) **Reward_#_ID** *uint16*: ID of flag to modify. **Reward_#_Min_Value** *int16*: Minimum short value to modify flag's current value by. **Reward_#_Max_Value** *int16*: Maximum short value to modify flag's current value by. **Reward_#_Modification** *enum* (``Assign``, ``Decrement``, ``Increment``): Set value, subtract value, or add value. Non-flags --------- Achievement ``````````` **Reward_#_Type** *enum* (``Achievement``) **Reward_#_ID** *string*: ID of achievement to grant. Only specific achievements can be granted as a reward. Airdrop ```````` **Reward_#_Type** *enum* (``Airdrop``) **Reward_#_Use_Random_Airdrop_Node** *bool*: If true, call in airdrop at a random airdrop node placed in the level editor. **Reward_#_Cargo** *GUID or uint16*: Optional spawn table ID overriding which items to drop. **Reward_#_Spawnpoint** *string*: Location to call in the airdrop, using the spawnpoint name as set in the nodes level editor. Currency ```````` Refer to :ref:`Currency ` documentation. **Reward_#_Type** *enum* (``Currency``) **Reward_#_GUID** *string*: GUID of currency asset. **Reward_#_Value** *int*: Amount of currency to reward. Cutscene Mode ````````````` Not as exciting as it sounds. While active, the first-person viewmodel is hidden and certain item actions like shooting are disabled. It's saved/loaded, but resets on death. **Reward_#_Type** *enum* (``Cutscene_Mode``) **Reward_#_Value** *bool*: Whether cutscene mode should currently be active. .. _doc_npc_asset_rewards:effect: Effect ``````` **Reward_#_Type** *enum* (``Effect``) **Reward_#_GUID** :ref:`Asset Pointer `: :ref:`Effect Asset` to spawn. **Reward_#_Spawnpoint** *string*: Location to spawn the effect, using the spawnpoint name as set in the nodes level editor. For example, ``Liberator_Jet``. **Reward_#_AtPlayerPosition** *bool*: If true, spawn the effect at the target player's position. **Reward_#_IsReliable** *bool*: If true, multiplayer will ensure the effect is replicated. If false, it won't be retransmitted if the packet is lost. Defaults to true. **Reward_#_RelevantDistance** *float*: If set, overrides the default multiplayer relevant distance of 128 meters. Defaults to -1. **Reward_#_OnlyRelevantToInstigator** *bool*: If true, only the player triggering this reward will see the effect. Defaults to false. Takes priority over ``RelevantDistance`` if set. .. _doc_npc_asset_rewards:event: Event ````` **Reward_#_Type** *enum* (``Event``) **Reward_#_ID** *string*: ID of event to broadcast. This can be used by c# plugins with the ``NPCEventManager`` class, or Unity events with the :ref:`NPC Global Event component `. For example, when an event with ID "Fireworks" is broadcast all of the components with event ID "Fireworks" will have their corresponding Unity event triggered as well, in this case perhaps to spawn a fireworks effect. **Reward_#_Replicate** *bool*: If true, event is triggered on clients as well as the server. Defaults to true. If false, event is only triggered on authority (singleplayer/server). **Reward_#_InstigatorOnly** *bool*: If true, event is run only for the player triggering the reward. Defaults to false. Takes priority over ``Replicate``. In multiplayer this means the event is only broadcast for the triggering client, not the server. Experience `````````` **Reward_#_Type** *enum* (``Experience``) **Reward_#_Value** *int*: Amount of experience to reward. Item ```` **Reward_#_Type** *enum* (``Item``) **Reward_#_ID** *uint16*: ID of item to reward. **Reward_#_Amount** *int*: Amount of item to reward. **Reward_#_Auto_Equip** *bool*: If true, the item should be automatically equipped by the player (if possible). Auto-equipping isn't possible if another item in the same slot is already equipped. Defaults to false. **Reward_#_Ammo** *byte*: Override for the amount of ammuntion that should be loaded in the item reward. **Reward_#_Barrel** *uint16*: Override for the barrel attachment that should be attached to the item reward. **Reward_#_Grip** *uint16*: Override for the grip attachment that should be attached to the item reward. **Reward_#_Magazine** *uint16*: Override for the magazine attachment that should be attached to the item reward. **Reward_#_Origin** :ref:`doc_data_eitemorigin`: Set the item origin. For example, setting the origin to ``Admin`` will cause items to spawn at full quality. Defaults to ``Craft``. **Reward_#_Sight** *uint16*: Override for the sight attachment that should be attached to the item reward. **Reward_#_Tactical** *uint16*: Override for the tactical attachment that should be attached to the item reward. Item_Random ``````````` **Reward_#_Type** *enum* (``Item_Random``) **Reward_#_ID** *uint16*: ID of spawn table that the random item reward should come from. **Reward_#_Amount** *int*: Amount of item to reward. **Reward_#_Auto_Equip** *bool*: If true, the item should be automatically equipped by the player (if possible). Auto-equipping isn't possible if another item in the same slot is already equipped. Defaults to false. **Reward_#_Origin** :ref:`doc_data_eitemorigin`: Set the item origin. For example, setting the origin to ``Admin`` will cause items to spawn at full quality. Defaults to ``Craft``. Hint ```` **Reward_#_Type** *enum* (``Hint``) **Reward_#_Text** :ref:`doc_data_richtext`: Debug text that is shown when the asset's :ref:`localization file ` is empty. If a localization file has been included then the localized text is used instead. **Reward_#_Duration** *float*: Duration of the hint, in seconds. Defaults to 2 seconds. .. note:: For localized hints to work in multiplayer, please add ``Keep_Localization_Loaded true`` to the owning asset. Otherwise, the server's language is used. This is necessary because the server doesn't currently have a way to reference the reward itself (which the client has the text loaded for), instead the asset ID and localization key are replicated. Player Life Food ```````````````` **Reward_#_Type** *enum* (``Player_Life_Food``) **Reward_#_Value** *int*: Amount of food to add. Can be negative to decrease food. Player Life Health `````````````````` **Reward_#_Type** *enum* (``Player_Life_Health``) **Reward_#_Value** *int*: Amount of health to add. Can be negative to decrease health. Player Life Stamina ``````````````````` **Reward_#_Type** *enum* (``Player_Life_Stamina``) **Reward_#_Value** *int*: Amount of stamina/energy to add. Can be negative to decrease stamina level. Player Life Virus ````````````````` **Reward_#_Type** *enum* (``Player_Life_Virus``) **Reward_#_Value** *int*: Amount of virus to add. Can be negative to decrease virus level. Player Life Water ````````````````` **Reward_#_Type** *enum* (``Player_Life_Water``) **Reward_#_Value** *int*: Amount of water to add. Can be negative to decrease water. Player Spawnpoint ````````````````` **Reward_#_Type** *enum* (``Player_Spawnpoint``) **Reward_#_ID** *string* Override the player's default spawn location, using the ID of a spawnpoint node or the name of a map location node, as set in the level editor. For example, ``Liberator_Jet``. Saved and loaded between sessions. If empty, the override is removed and the default spawns are used. The ``SetNpcSpawnId`` admin command is useful for testing this. .. hint:: On the Buak map, the player can talk with Kira to claim a room in the Factory using this reward type. Quest ````` **Reward_#_Type** *enum* (``Quest``) **Reward_#_ID** *uint16*: Quest ID to give as a reward. Remove Zombies `````````````` Kills zombies that match a set of filters. **Reward_#_Type** *enum* (``Remove_Zombies``) **Reward_#_Zombie** *enum*: Which "type" of zombie to remove, the same list as zombie kills condition. To-do: move to its own page. Defaults to ``None`` in which case all zombie types match. **Reward_#_LevelTableOverride** *int*: Unique ID of a zombie type shown in the level editor. If set, only zombies spawned from this table are removed. Defaults to ``-1`` in which case all zombie tables match. **Reward_#_Nav** *byte*: Index of the navmesh that zombies should be removed from, seen as visible in the level editor. Defaults to ``255`` in which case all navmeshes match. Reputation `````````` **Reward_#_Type** *enum* (``Reputation``) **Reward_#_Value** *int*: Amount of reputation to reward. Rewards List Asset `````````````````` **Reward_#_Type** *enum* (``Rewards_List_Asset``) **Reward_#_GUID** :ref:`Asset Pointer `: :ref:`Rewards List` to grant directly, or :ref:`Spawn Table ` to resolve into one. Teleport ```````` **Reward_#_Type** *enum* (``Teleport``) **Reward_#_Spawnpoint** *string*: Location to teleport the player to as a reward, using the ID of a spawnpoint node as set in the level editor. For example, ``Liberator_Jet``. Vehicle ``````` **Reward_#_Type** *enum* (``Vehicle``) **Reward_#_ID** : ID of Vehicle to be given. **Reward_#_Spawnpoint** *string*: Location to spawn the vehicle in as a reward, using the ID of a spawnpoint node as set in the level editor. For example, ``Liberator_Jet``. If an ID is not provided, the vehicle will spawn above the NPC. **Reward_#_PaintColor** *color*: If set, overrides color of spawned vehicle. Vehicle redirector asset's ``SpawnPaintColor`` and vehicle asset's ``DefaultPaintColors`` are bypassed. Zombie `````` Respawns zombie(s) at named Spawnpoint nodes. If insufficient dead zombies are available to respawn, alive zombies are converted to the appropriate type and teleported. .. note:: Spawnpoints must be within a navmesh. **Reward_#_Type** *enum* (``Zombie``) **Reward_#_Zombie** *enum*: Which "type" of zombie to spawn, the same list as zombie kills condition. To-do: move to its own page. **Reward_#_Spawnpoint** *string*: Where to spawn the zombies, using the name as set in the nodes level editor. When multiple nodes share a name each zombie is spawned at a random node. **Reward_#_LevelTableOverride** *int*: Unique ID of a zombie type shown in the level editor. If set, the zombie spawned will use that type. Defaults to -1. **Reward_#_SpawnQuantity** *int*: Amount of zombies to spawn. **Reward_#_CooldownId** *string*: If set, only spawn if a named global cooldown (shared between all players) has passed. **Reward_#_CooldownDuration** *float*: Seconds since CooldownId last ran before this reward can spawn zombies again. .. _doc_npc_asset_rewards:localization: Localization ------------ Rewards lists properties can be localized in the asset's localization file. **Reward_#**: Localization for the name of the reward as it appears in user interfaces. .. tip:: Localization properties follow the same rules as other parts of the rewards list – including needing to use the correct prefix. For example, the property name for a localized hint on an interactable object would be ``Interactability_Reward_#``. ================================================ FILE: npcs/vendor-asset.rst ================================================ .. _doc_npc_asset_vendor: Vendor Assets ============= **GUID** *32-digit hexadecimal*: Refer to :ref:`GUID ` documentation. **Type** *enum* (``Vendor``) **ID** *uint16*: Must be a unique identifier. Buying ------ Properties pertaining to items that the vendor is willing to buy from players. Vendors can set conditions for the items they are buying. These conditions are prefixed with ``Buying_#_``. For example, ``Buying_0_Conditions 1``. For more information, refer to the documentation for :ref:`Conditions ` and :ref:`Rewards ` respectively. **Buying** *byte*: Total number items being bought by the vendor. **Buying_#_ID** *uint16*: ID of item to buy from the player. **Buying_#_Cost** *uint32*: Amount of currency to pay the player. Defaults to experience points as the currency, unless the Currency property has been set. Selling ------- Properties pertaining to items or vehicles that the vendor is willing to sell to players. Vendors can set conditions for the items/vehicles they are selling. These conditions are prefixed with ``Selling_#_``. For example, ``Selling_0_Conditions 1``. For more information, refer to the documentation for :ref:`Conditions ` and :ref:`Rewards ` respectively. **Selling** *byte*: Total number of items/vehicles being sold by the vendor. **Selling_#_Type** *enum* (``Item``, ``Vehicle``): Type of asset being sold. **Selling_#_ID** *uint16*: ID of item/vehicle to sell to the player. **Selling_#_Cost** *uint32*: Amount of currency to pay the vendor. Defaults to experience points as the currency, unless the Currency property has been set. **Selling_#_Spawnpoint** *string*: Location to spawn the purchased vehicle, using the ID of a spawnpoint node as set in the level editor. For example, ``Liberator_Jet``. If an ID is not provided, the vehicle will spawn above the NPC. **Selling_#_PaintColor** *color*: If set, overrides color of purchased vehicle. Vehicle redirector asset's ``SpawnPaintColor`` and vehicle asset's ``DefaultPaintColors`` are bypassed. **Selling_#_Ammo** *byte*: Override for the amount of ammuntion that should be loaded in the item sold. **Selling_#_Barrel** *uint16*: Override for the barrel attachment that should be attached to the item sold. **Selling_#_Grip** *uint16*: Override for the grip attachment that should be attached to the item sold. **Selling_#_Magazine** *uint16*: Override for the magazine attachment that should be attached to the item sold. **Selling_#_Sight** *uint16*: Override for the sight attachment that should be attached to the item sold. **Selling_#_Tactical** *uint16*: Override for the tactical attachment that should be attached to the item sold. Other Properties ---------------- **Disable_Sorting** *flag*: Disable vendor sorting. **Currency** *string*: GUID of the :ref:`currency asset ` to use as currency instead of experience points. **FaceOverride** *byte*: Optional index of face image to use when this vendor is opened. Face is reset to character's default when unspecified or when a new message is opened. Localization ------------ **Name** *string*: Vendor name in user interfaces. **Description** :ref:`doc_data_richtext`: Vendor description in user interfaces. **Buying_#_Description** :ref:`doc_data_richtext`: If set, overrides item description shown in the vendor menu. I.e., how the vendor would describe the item rather than how the player would. **Selling_#_Description** :ref:`doc_data_richtext`: Same as **Buying_#_Description**. ================================================ FILE: requirements.in ================================================ # Base packages pygments==2.20.0 sphinx==8.1.3 sphinx_rtd_theme==3.0.2 # Sphinx/RTD dependencies ######################### # Sphinx-RTD-Theme dependency. Previously needed to be manually specified. Likely safe to remove (and let it be auto-generated in requirements.txt). #sphinxcontrib-jquery # Sphinx extensions ################### # Code tabs extension to display codeblocks in different languages as tabs. sphinx-tabs==3.4.7 # Adds a 'copy' button to the right of codeblocks sphinx-copybutton==0.5.2 # Custom 404 error page sphinx-notfound-page==1.1.0 # OpenGraph support (URLs posted offsite appear as OneBox embeds) sphinxext-opengraph==0.13.0 # 2D plotting library. Not currently used but was previously required. Might be safely removable. matplotlib==3.8.0 # Embed videos in documentation pages. Not currently used. #sphinxcontrib-video==0.4.1 ================================================ FILE: requirements.txt ================================================ # # This file is autogenerated by pip-compile with Python 3.10 # by the following command: # # pip-compile requirements.in # alabaster==1.0.0 # via sphinx babel==2.17.0 # via sphinx certifi==2026.1.4 # via requests charset-normalizer==3.4.4 # via requests contourpy==1.3.2 # via matplotlib cycler==0.12.1 # via matplotlib docutils==0.21.2 # via # sphinx # sphinx-rtd-theme # sphinx-tabs fonttools==4.61.1 # via matplotlib idna==3.11 # via requests imagesize==1.4.1 # via sphinx jinja2==3.1.6 # via sphinx kiwisolver==1.4.9 # via matplotlib markupsafe==3.0.3 # via jinja2 matplotlib==3.8.0 # via -r requirements.in numpy==1.26.4 # via # contourpy # matplotlib packaging==25.0 # via # matplotlib # sphinx pillow==12.2.0 # via matplotlib pygments==2.20.0 # via # -r requirements.in # sphinx # sphinx-tabs pyparsing==3.3.1 # via matplotlib python-dateutil==2.9.0.post0 # via matplotlib requests==2.33.0 # via sphinx six==1.17.0 # via python-dateutil snowballstemmer==3.0.1 # via sphinx sphinx==8.1.3 # via # -r requirements.in # sphinx-copybutton # sphinx-notfound-page # sphinx-rtd-theme # sphinx-tabs # sphinxcontrib-jquery # sphinxext-opengraph sphinx-copybutton==0.5.2 # via -r requirements.in sphinx-notfound-page==1.1.0 # via -r requirements.in sphinx-rtd-theme==3.0.2 # via -r requirements.in sphinx-tabs==3.4.7 # via -r requirements.in sphinxcontrib-applehelp==2.0.0 # via sphinx sphinxcontrib-devhelp==2.0.0 # via sphinx sphinxcontrib-htmlhelp==2.1.0 # via sphinx sphinxcontrib-jquery==4.1 # via sphinx-rtd-theme sphinxcontrib-jsmath==1.0.1 # via sphinx sphinxcontrib-qthelp==2.0.0 # via sphinx sphinxcontrib-serializinghtml==2.0.0 # via sphinx sphinxext-opengraph==0.13.0 # via -r requirements.in tomli==2.3.0 # via sphinx urllib3==2.7.0 # via requests ================================================ FILE: sdg/dat-editing-code.rst ================================================ .. _doc_dat_editing_code: Dat Editing Code ================ This document aims to clarify some of the thought process behind the "editable" and "metadata" additions to the ``UnturnedDat`` module. We'll refer to ``DatValue``, ``DatDictionary``, and ``DatList`` as the "data classes." They were marked public in the first version of the ``UnturnedDat`` module. They have been kept public for backwards compatibility with user code, but use of ``IDatValue``, ``IDatDictionary``, and ``IDatList`` should be preferred where possible. This will allow us to more easily maintain compatibility if additional changes are necessary. When parsing with metadata is enabled, the data classes are wrapped/proxied in ``*WithMetadata`` classes, and the ``*WithMetadata`` classes are inserted into the document hierarchy. Initially these were a subclass of the data class, but we wanted to keep the inheritance hierarchy shallow especially when adding the ``Editable*`` classes. Along with editing support, we intend to use metadata for more descriptive asset parsing errors in the future. Why not store metadata in data classes directly? We didn't want to introduce any overhead for players running without the ``-ParseAssetMetadata`` command-line flag. Also, not all nodes have metadata (only nodes created by the parser have metadata). The ``IEditable*`` interfaces allow user code to modify documents while mostly preserving comments, white space, file layout, and line numbering. ``IEditable`` types wrap/proxy data similar to metadata. They store additional info like comment overrides, preferred line numbers, margins, and insertion order. This preserves any parsed metadata rather than clobbering it. Edits modifying parsed data wrap ``*WithMetadata`` classes, whereas edits **adding** data wrap the data classes directly. .. warning:: Comments are associated with the node following them. If a comment isn't associated with a node (separated by empty lines) it will be lost (currently). We could *potentially* work around this by adding a "FloatingComment" node type, but it's low priority. ================================================ FILE: sdg/hosting-servers-using-private-workshop-files.rst ================================================ .. _doc_hosting_servers_using_private_workshop_files: Hosting Servers Using Private Workshop Files ============================================ Unfortunately, the dedicated server cannot login to a Steam account to download private workshop files. So, a workaround is necessary. By logging into steamcmd you can download the workshop file using your account: #. ``login (credentials)`` #. ``workshop_download_item 304930 (workshopfileid)`` This will download the file into the steamcmd folder at ``steamapps/workshop/content/304930/(workshopfileid)``. You can now create a symbolic link between the server and the workshop file. For example on Linux testing map ``MyMap``, open the U3DS folder and use: ``ln -S ../../workshop/content/304930/(workshopfileid)/MyMap Maps/MyMap`` The workshop file ID should still be added to ``WorkshopDownloadConfig.json`` so that clients enable it when joining. ================================================ FILE: sdg/legacy-id-availability.rst ================================================ .. _doc_legacy_id_availability: Legacy ID Availability ====================== Ideally, new content should use GUIDs when possible. Certain asset types—such as items—still rely heavily on legacy IDs. That said, they can be referenced by GUID in many cases. For example, NPC clothing and item spawn tables can reference items by GUID. To find available legacy IDs: #. Press ``F1`` in the main menu **Workshop** sub-menu. #. Click **Export Asset IDs**. #. Open ``Extras/AssetIDs/All Assets/Grouped by Legacy Category``. #. Each legacy asset category (e.g., Items) has a corresponding ``Legacy ID Availability.csv`` file listing IDs and whether they are reserved for vanilla content. ================================================ FILE: sdg/source-code.rst ================================================ .. _doc_source_code: Source Code =========== We are hoping to release Unturned's source code in 2025. This would allow anyone to create their own spin on the game. From minor balance changes and item additions, to total conversions with new gameplay elements. .. warning:: **This information is subject to change.** Details and timelines regarding the release could be different. There's a lot of moving parts we need to consider as we work towards this goal! There are some major obstacles that need to be addressed before we can achieve this. Some of these include: 1. | Seeking legal advice. We need to review any existing license agreements, determine any intellectual property we should retain (e.g., the "Unturned" trademark for future games), and more advice about open sourcing the project. 2. | Replacing third-party code and assets that cannot be open sourced. Most of the game's code should already be open sourceable. Certain third-party assets likely cannot be included, and some code will need to be replaced from scratch. As examples: edge highlighting should be converted to Unity's post-processing stack, water—currently a Unity 4 asset—will need a fallback, and zombie pathfinding may be able to use Unity's newer navmesh system. Tackling these issues – and others – is necessary before the game is made open source. FAQ --- **Q. Will the official Steam version continue receiving updates?** Yes—we plan to continue maintaining the official Steam version with new content updates and bug fixes. **Q. Why do you want to make the game open source?** Unturned's greatest strength is our passionate community. Releasing the source files allows you and other players to further build upon the game as you see fit. Building a lasting legacy for the game regardless of the changes we make or how many years pass from now. **Q. Will you accept pull requests?** Our current goal is to simply allow players to create their own derivatives of the game. However – we haven't completely ruled this out, and we're sure there's interest in seeing community-contributed code accepted into the game. **Q. Will the open source project be kept up-to-date with the version used by the official game?** This is our current intention. **Q. Is there anything I can't do/use?** This is an example of something that requires further legal review before we're comfortable giving an answer. **Q. Is there anything that WON'T be available?** Yes. Some content will be intentionally stripped from the open source version of the project. For example, support for the BattlEye anti-cheat. This is something that requires further review before we're comfortable giving an exhaustive list. **Q. Could I publish my derivative work on Steam?** This requires more legal review (and consulting with Steam)! Ideally, something like that would be permissible. Possibly similar to how some games' mods (e.g., for Portal 2 and Team Fortress 2) have dedicated Store pages. https://store.steampowered.com/about/communitymods/ **Q. Will there be documentation?** We are not focused on creating documentation specifically for this purpose. However, some preexisting documentation may be helpful, along with any comments included in the source code. Community-contributed documentation on this topic may be accepted. **Q. Will other versions of Unturned (1.x, 2.x) become open-source?** We may explore this idea in the future, but this is not a priority for us at this time. ================================================ FILE: sdg/test-steam-items.rst ================================================ .. _doc_test_steam_items: Testing Steam Items =================== .. note:: Only applicable in development builds and the Unity editor. A temporary test inventory can be loaded from a file named ``TestInventory.dat`` in the game folder. It contains an ``Items`` list of dictionaries, each with the following properties: DefinitionId :ref:`int32 ` :::::::::::::::::::::::::::::::::::::::::::::::::: Steam item definition ID. The item can exist locally, i.e., not in the Inventory Service. ---- Quantity :ref:`int32 ` ``1`` :::::::::::::::::::::::::::::::::::::::::::::::::::: Number of items in stack. Optional. ---- InstanceId :ref:`uint64 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::: By default, a relatively stable instance ID is automatically created for each test item. Can optionally be overridden using this property if necessary. ---- Tags :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::: Dynamic per-item tags. Optional. (e.g., manually specifying ragdoll effect, crafted mythical, and/or kill counter) ---- RagdollEffect *enum* :::::::::::::::::::: Optional. Any of the ragdoll effect names. ---- ParticleEffect :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Optional legacy ID of a mythical effect. Works as if the item were crafted with this mythical effect. Useful for testing mythical effects on skins. (Unboxed mythicals unfortunately use an older, less flexible system.) ---- MythicSearchId :ref:`uint16 ` ``0`` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Optional legacy ID of a mythical effect. Useful for testing mythical effects on cosmetic items without knowing the DefinitionId of the variant. Set DefinitionId to the ID of the non-mythical variant of the item. ---- KillCounter *enum* :::::::::::::::::: Optional. Can be set to ``Player`` or ``Total``. ================================================ FILE: sdg/unity-project.rst ================================================ .. _doc_unity_project: Unity Project ============= Downloading ----------- Unturned's project files are stored using the `Git `_ version control system (`VCS `_). We have a separate document outlining how to work with Git, from downloading to contributing changes: :ref:`doc_using_git`. Getting Started --------------- You'll need the same version of the Unity editor as described in :ref:`doc_getting_started:installing_unity`. You can double-check the editor version in ``ProjectSettings/ProjectVersion.txt``. Blender must be available during first import to load certain meshes. On Linux, ``blender`` must be in your ``PATH``. Unfortunately, Steam needs to be running, even to launch the game in the editor. This does make certain tasks like debugging multiplayer harder. Unturned 3 is very tightly integrated with the Steam API, so this requirement is unlikely to change. Certainly an important lesson for future games: Plan ahead to support swapping out platform APIs. The editor needs a copy of the core assets. The easiest option for this is to enable :ref:`Load Core Asset Bundle From Steam Install `. Alternatively, :ref:`Export Core Asset Bundle `. Most gameplay requires remote procedure calls (RPCs) to function properly. Even singleplayer is essentially a one-player server. The RPC code is automatically generated, but this is still a manual step in the editor: #. Open **Window** > **Unturned** > **Net Gen** #. Click **Generate** #. Tab out and back in to ensure the scripts are imported Finally, to run the game in the editor, open ``Assets/Game/Sources/Scenes/Setup.unity`` and click Play. .. warning:: We recommend closing Unity's **Hierarchy** window in-game except when you need it. Unturned's scenes contain mostly top-level game objects for optimization purposes with the drawback of slowing down the Hierarchy window. For more information, `Scenes Structure > Hierarchy depth and count `_. Editor Preferences ------------------ Unfortunately, Unturned doesn't support hot-reloading. If modifying code while Unity is open, we recommend changing **Script changes while playing** to **Recompile after playing**. Play Mode Settings ------------------ An editor window is available from Window > Unturned > Editor Settings. Primarily it sets :ref:`options ` that are otherwise specified on the command-line. **Auto Load Level and Auto Load Mode**: Set to a level's folder name to bypass the menu, going from the loading screen directly into singleplayer or the level editor. **Glazier**: Overrides default :ref:`doc_glazier`. .. _load_core_asset_bundle_from_steam_install: **Load Core Asset Bundle From Steam Install**: If enabled, core.masterbundle is loaded from the Steam version of Unturned rather than the local copy. Troubleshooting --------------- Check Unity's log files. On Windows there's a shortcut in the project folder to the most recent log file ``Unity Editor.log`` as well as the containing folder ``UnityEditor Logs Folder``. File Organization ----------------- One could argue "organization" is a misnomer in this case. ``Assets/CoreMasterBundle`` contains most of the Unity assets loaded at runtime. This is the only asset bundle exported for vanilla content. ``Assets/Game/Sources`` contains all of the source (e.g., ``.blend``) and imported (e.g., ``.fbx``) files for Unity assets exported in the asset bundle. ``Assets/Resources`` are Unity assets loaded by the ``Resources`` class. Introducing new files to this folder should be avoided if possible. ``Assets/Runtime`` contains all of the player code. Certain newer features have their own folders per-assembly-definition, but most game code is in the ``Assembly-CSharp`` folder. It would be nice to rename it, but as far as I'm aware we can't do this without breaking script references in asset bundles (as of 2024-10-18). ``Assets/Runtime/Assembly-CSharp/NetGen`` is all generated networking code and excluded from Git. The ``Builds`` folder contains exported Unity players, the vanilla :ref:`"masterbundle" (asset bundle) `, and - unintuitively - all of the important non-Unity files like :ref:`.dats `. This becomes clearer when remembering the overly-tight integration with Steam. Each subdirectory of ``Builds`` is a Steam depot (except CoreAssetBundle and Test). For future games we would instead automatically **copy** the files from the project output into a Steam depot structure. *sigh* ``Economy`` contains all of the icons and configuration files for the Steam Inventory Service. It's actually gotten a lot tidier since we can refactor it without affecting mods or plugins. ``IDs`` contains spreadsheets of vanilla legacy ID usage. This is hopefully obsolete after 3.24.6.0 added the Menu > Workshop > F1 > Log Asset IDs tool. Exporting Core Asset Bundle (``core.masterbundle``) --------------------------------------------------- .. _export_core_asset_bundle: #. Open Window > Unturned > Master Bundle Tool. #. Expand **Asset Bundles** and check the box next to **core.masterbundle**. #. Expand **Master Bundles**. #. Click **...** and navigate to the Unturned project root, ``Builds/CoreAssetBundle`` directory. #. Click **Export**. Continuous Integration ---------------------- For each commit, `Jenkins `_ builds the project and runs tests, optionally uploading to a Steam branch. At the time of writing (2024-10-18) the Jenkins server is locally hosted and not accessible over the Internet. It **mostly** works with Pipelines using a script at ``Build_Scripts/Jenkinsfile.txt``. Launching the correct version of Unity relies on ``Build_Scripts/JenkinsBootstrapper.exe`` built from ``JenkinsBootstrapper`` in the project root. It expects Unity to be installed in one of these paths: - ``C:\UnityEditors`` - ``C:\Unity Editors`` - ``C:\Program Files\Unity\Hub\Editor`` (Yeah, sadly the development and build processes are very Windows-centric.) ================================================ FILE: sdg/using-git.rst ================================================ .. _doc_using_git: Using Git ========= First time setup: #. Fork #. Clone #. Add Upstream Development loop: #. Branch #. Commit and Push (repeat) #. Sync with Upstream #. Pull Request GitHub offers a `more thorough walkthrough to forking, cloning, and syncing changes `_. Fork ---- The first step is to "fork" the game. This creates your own personal copy to develop and experiment with. Visit the game repository, click the down arrow next to "Fork", and select "Create a new fork." Clone ----- You can use the Git CLI to clone (download) the files, but we recommend using a GUI. The Git website `lists a variety of great, free GUI tools `_ including `GitHub Desktop `_ and `Sourcetree `_. Nelson uses `Fork `_, however it has an upfront price of $60 USD at the time of writing (2025-02-25). From your forked repository, click the **Code** button to get the link: .. image:: img/copy-git-url.png :scale: 50 % :alt: Clone repository dropdown in GitHub's web GUI. Clone a local copy of your forked repository (in Sourcetree in this example): .. image:: img/cloning-in-sourcetree.png :scale: 50 % :alt: Entering Git URL into Sourcetree app. Branch ------ Create a branch for your custom changes. You'll periodically **commit** changes to your branch. For example, if working on a big crafting balance overhaul you might create a branch named ``dev-crafting-balance``. Commit ------ Commits save a selection of your changes. Commit often! Don't be afraid to commit. For example, you might commit "Added stacked logs barricade" or "Fixed gap in potato item model". It's especially useful if (when) something goes wrong. For example, if a change you were testing turns out to be a bad idea, it's easy to roll back to the previous commit. Add Upstream ------------ To enable you to keep your forked repository up-to-date, the next step is to add the base game repo as another **Remote** (server). There should be an option to **Add Remote** (in Sourcetree in this example): .. image:: img/add-remote.png :scale: 50 % :alt: Finding the add remote button in Sourcetree app. Set the remote name to ``upstream``. It can technically be anything, but upstream is the conventional name. For the remote URL use the ``.git`` URL from the base game's **Code** dropdown in the GitHub web GUI. Syncing with Upstream --------------------- GitHub has a `more detailed article about this `_. Your fork doesn't automatically stay up-to-date with changes in the base game. It's important to sync up occasionally, or before submitting a pull request. #. **Fetch** news from all remotes. This updates the changes your local copy knows about. #. **Checkout** the ``main`` branch locally. (Switching away from your custom branch.) #. **Pull** changes from ``upstream/main`` into your local ``main``. #. **Checkout** your custom branch. #. **Merge** the ``main`` branch into your custom branch. This may require resolving merge conflicts. .. note:: This can be done in a quicker, more straightforward fashion, but this guide doesn't want to risk clobbering your changes. Push ---- Pushing your changes uploads them to GitHub. By pushing occasionally you gain the added benefit of an online backup of your work! Pull Request ------------ GitHub again has an `article about pull requests `_. Create a pull request to ask for your changes to be added to the base game. From your fork's repository in GitHub's web GUI there should be a button to **Compare & pull request**. Font Atlases Dirty ------------------ It's possible for characters not included in the font atlases to show up while playing in Unity. For example, from workshop files on the main menu or signs in multiplayer. These get added to the fallback font atlases, marking them changed in git. There's probably a better way to work around this, but one way is to tell git not to detect them as changed: ``git update-index --skip-worktree "Assets/Resources/UI/Glazier_uGUI/LiberationSans Fallback.asset" "Assets/Resources/UI/Glazier_uGUI/NotoSansCJK Fallback.asset"`` To undo this (for example, when needing to discard changes): ``git update-index --no-skip-worktree "Assets/Resources/UI/Glazier_uGUI/LiberationSans Fallback.asset" "Assets/Resources/UI/Glazier_uGUI/NotoSansCJK Fallback.asset"`` Clarifying Git vs GitHub ------------------------ It's a common misconception that `Git `_ and `GitHub `_ are the same thing! Git is the underlying version control system (`VCS `_). GitHub is a `software forge `_ which hosts Git services. ================================================ FILE: servers/bookmark-host.rst ================================================ .. _doc_servers_bookmark_host: Bookmark Host ============= Configuring the **Bookmark Host** property along with a :ref:`Login Token ` enables the bookmark button, allowing players to find your server even after an IP or port change. By default the game supports Steam's built-in Favorites and History server lists. These lists remember your server by the combination of IPv4 address and port, so if your address or port change the link is broken. Steam mitigates this if you have a :ref:`GSLT ` assigned by automatically updating the saved address, but this doesn't happen in realtime. These lists also aren't compatible with the newer :ref:`Fake IP ` feature. Considering the trend toward Fake IP, a replacement was necessary, not to mention a popular request from server hosts. Thankfully, with GSLTs in widespread use now and providing a stable persistent ID, the client can save custom per-server bookmark data. The intention is to make bookmarks a better alternative to the legacy favorites/history lists, including proper support for IPv6 at some point. At the time of writing (2024-05-24) the client doesn't save history using the bookmark host property yet, but it should be added once more hosts opt-in. To enable bookmarking, set ``BookmarkHost`` in your :ref:`doc_servers_server_configuration` to one of these formats: 1. | A DNS entry with an ``A`` record pointing to your server's public IP. For example, if you own the "example.com" domain you could add an A record "myunturnedserver" pointing at your game server IP and set ``BookmarkHost`` to "myunturnedserver.example.com". In this case the client will save your server's current port number, so the IP address can change but the port can't. If your server doesn't have a static public IP you could use dynamic DNS to update the DNS record periodically. Note that this option is inapplicable for servers using Fake IP because both the IP and port are randomly assigned after each restart. 2. | The URL of a custom web API to return the address, and optionally the port. Clients perform a GET request if ``BookmarkHost`` begins with "http://" or "https://". The response should be plain text. Examples of valid responses include: - 127.0.0.1 - 127.0.0.1:27015 - myunturnedserver.example.com - myunturnedserver.example.com:27015 The hosts of Pandahut have generously shared an example implementation consisting of a server plugin which updates the latest server address on a custom backend, and a web request handler to serve the latest address to clients. Note that we don't necessarily recommend using this program as-is, it's just an example: `BookmarkHostPlugin by PandahutMushy `_ ================================================ FILE: servers/command-io.rst ================================================ .. _doc_servers_command_io: Command IO ========== By default Unturned executes commands from console input, and logs information to console output. This can be overridden however, for example to interact with an external process or remote console. To replace the vanilla implementation: 1. Create a class that implements the ICommandInputOutput interface. 2. Get the CommandWindow singleton from Dedicator.commandWindow. 3. Pass instance to CommandWindow.setIOHandler. 4. (Optional) Specify ``-NoDefaultConsole`` on the command-line to disable vanilla console. ================================================ FILE: servers/debugging-exceptions.rst ================================================ .. _doc_debugging_exceptions: Debugging Exceptions ==================== In release builds it can be difficult to narrow down exactly what's causing an exception. Thanks to `DiFFoZ post here `_ for sharing a technique to find the line number, summarized here for posterity: #. Unity logs an IL offset in square brackets to the ``Player.log`` file. This is not included in the stack trace sent to the game for the ``Client.log`` file unfortunately. For example 0x003db in this log: .. code-block:: text at SDG.Unturned.ResourceSpawnpoint..ctor (System.Byte newType, System.UInt16 newID, System.Guid newGuid, UnityEngine.Vector3 newPoint, System.Boolean newGenerated, SDG.Unturned.NetId netId) [0x003db] in <08e91a6d9e1d4bd5bf2e982fa4148205>:0 ^^^^^^^^^ #. Open the related assembly (in this case ``Assembly-CSharp.dll``) in a c# decompiler like DnSpy or ILSpy. #. In ILSpy use ``Search`` (Ctrl+Shift+F) to find the method from the stack trace. #. Change display mode to ``IL with C#``. #. Find related line, ``IL_03db`` in the 0x003db example case. ================================================ FILE: servers/dedicated-workshop-update-monitor.rst ================================================ .. _doc_servers_workshop_update_monitor: Dedicated Workshop Update Monitor ================================= When hosting a server with content from the `Steam Workshop `_ it may be desirable to restart the server when updates are released by creators. In particular, maps have their own version numbers which the server list uses to test compatibility before players connect. By default the game monitors for changes to the hosted map. When a change is detected it notifies players via chat and shuts down the server after a timer. This can be overridden however, for example to notify players with a custom modal prompt and perform a custom restart process. To replace the vanilla implementation: 1. Create a class that implements the IDedicatedWorkshopUpdateMonitor interface, or create a subclass of DedicatedWorkshopUpdateMonitor and override as-needed. 2. Bind the DedicatedWorkshopUpdateMonitorFactory.onCreateForLevel event and return the custom instance. ================================================ FILE: servers/fake-ip.rst ================================================ .. _doc_servers_fake_ip: Fake IP ======= Using a Steam **Fake IP** allows players to join your server by IP address without :ref:`port forwarding `. Unlike :ref:`Server Codes `, a server using Fake IP can be visible on the Internet server list (still without port forwarding) as long as you set a :ref:`Login Token `. To enable Fake IP, set ``Use_FakeIP`` to ``true`` in your :ref:`doc_servers_server_configuration`. After startup, you can run the ``CopyFakeIP`` command from the server console to copy the IP and port to your clipboard. Pasting this into the Host field of the Connect menu automatically moves the port to the Port field. Technical Details ----------------- Connecting by Fake IP utilizes `Steam Datagram Relay (SDR) `_. To quote that page: "Relaying the traffic protects your servers and players from DoS attack, because IP addresses are never revealed. All traffic you receive is authenticated, encrypted, and rate-limited. Furthermore, for a surprisingly high number of players, we can also find a faster route through our network, which actually improves player ping times." The downside of Fake IP as opposed to port forwarding is that the address and port will change after every restart, so, for example, a domain name cannot be used without custom scripts. Bookmarking ----------- Unfortunately, Fake IP is not compatible with Steam's built-in "Favorites" and "History" server lists. As an optional workaround, these servers can utilize our :ref:`Bookmarking ` feature instead. ================================================ FILE: servers/game-server-login-tokens.rst ================================================ .. _doc_servers_gslt: Game Server Login Tokens ======================== Unturned dedicated servers can be logged-in to Steam using a **Game Server Login Token** or **GSLT**. This provides a few benefits: #. If using Server Codes to connect, your code will remain linked to your GSLT between sessions. Otherwise, each time you start the server you will need to send your friends the new code. #. Servers without a GSLT are considered "anonymous" and are hidden from the Internet server list. #. Steam tracks your Favorites and History lists by address and port, but with a GSLT it can automatically transfer them if the server details change. This should happen within approximately 24 hours. (Verified in `issue #3980 `_ thanks to CyberAndrii and joeymisfit, and on `AlliedModders `_.) Creating GSLTs -------------- You can manually create GSLTs while logged in with your Steam account here: https://steamcommunity.com/dev/managegameservers Use Unturned's app ID ``304930``, and a memo to remind you which server the token is for. Unturned Configuration ---------------------- The GSLT can be set in one of two places depending on your preference: - With the ``Login_Token`` property in each :ref:`doc_servers_server_configuration` under the ``Browser`` section. OR - Using the ``GSLT`` command during startup. This can be specified in the ``Commands.dat`` file or on the command-line. Automating GSLTs ---------------- Valve provides an ``IGameServersService`` web API for managing GSLTs. Consult their documentation here: https://partner.steamgames.com/doc/webapi/IGameServersService ================================================ FILE: servers/glazier.rst ================================================ .. _doc_glazier: Glazier ======= Unity (the game engine Unturned runs on) has three different incompatible UI systems: 1. IMGUI 2. uGUI 3. UIToolkit Unturned has a feature nicknamed **Glazier** which abstracts the underlying UI system, allowing IMGUI, uGUI, or UIToolkit to be used. uGUI is Unity's current recommended UI system, but unfortunately some players run into visual artifacts and flickering UI with it. In those cases enabling IMGUI is recommended. Context ------- At its 2014 release into Early Access, Unturned used IMGUI, as it was Unity's only built-in UI system. For performance reasons, automatic layout was turned off in favor of manually specifying the position and size of UI elements. uGUI support was introduced in late 2020 for players running into issues with IMGUI. Unfortunately, IMGUI support needed to be kept for players facing different problems. Knowing that Unity was working on UIToolkit as a potential replacement, automatic layout was held off until an abstraction ideally supporting all three could be implemented. Upon updating to Unity 2021 LTS, runtime UIToolkit became available, and it could be integrated as a mostly functional Glazier option. With UIToolkit supported, automatic layout started being added to the game in the form of stats in item descriptions, multi-line text chat, and an updated main menu news feed. IMGUI ----- You can opt to use Unity's legacy UI system, IMGUI, by enabling a command-line argument: 1. Right-click Unturned in your Steam library 2. Click "Properties..." 3. Click "Select Launch Options..." 4. Add "-Glazier=IMGUI" without quotes **Pros:** - Faster on some systems because it has less overhead (no layout, no gameobjects). **Cons:** - Certain features like multi-line chat, extended item descriptions, and the main menu news feed are not supported in IMGUI mode. - Visual bugs (e.g. incorrect gamma) and input issues on both Mac and Linux. - Slower on some systems due to increased garbage collection. - Does not support layered interactive UI. Some menus like crafting and inventory selection use workarounds for this, and thus behave differently from their uGUI counterparts. - Plugin UIs are sorted underneath the game UI i.e. plugin UI cannot overlay. - Rich text does not fade out in chat. uGUI ---- This is Unturned's current default UI system, so opting in is not necessary. **Pros:** - Faster on some systems because the UI is not rebuilt every frame. - More user-friendly e.g. can drag items outside the inventory to drop them. - Looks better e.g. nicer scaling on high DPI monitors, foreground color universally supported. - Rich text fades out properly in chat. **Cons:** - Visual artifacts and flickering on some systems. - Slower on some systems because it has more overhead (layout, gameobjects). UIToolkit ---------- Integration into Unturned is experimental. It's not ready to be the default yet. You can check it out with a command-line argument: 1. Right-click Unturned in your Steam library 2. Click "Properties..." 3. Click "Select Launch Options..." 4. Add "-Glazier=UIToolkit" without quotes **Cons:** - Scroll views have incorrect content size (for now). With IMGUI and uGUI it was possible to explicitly specify the content size, whereas UIToolkit tries to automatically calculate it from the content bounds. Unfortunately, many of Unturned's scroll views have content clipping outside the intended content area, and so they don't appear correctly. For example, the location labels on the map can intersect the content border. - Text shadows and outlines are not as nice as with uGUI. ================================================ FILE: servers/openmod.rst ================================================ .. _doc_servers_openmod: OpenMod ======= `OpenMod `_ is a spiritual successor to :ref:`Rocket ` as developed by one of Rocket's original maintainers. It has its own plugin framework, but supports compatibility with existing Rocket plugins by integrating with RocketMod and LDM. Installation ------------ Installing OpenMod Using the RocketMod Installer Plugin (recommended) ````````````````````````````````````````````````````````````````````` 1. Download the latest OpenMod Installer Plugin for RocketMod from the `OpenMod.Installer.RocketMod repository `_. 2. Move it to the ``/Rocket/Plugins`` folder and restart your server. 3. Run ``/openmod install`` and follow the instructions. 4. Done! Now you can `start installing plugins `_. Installing OpenMod Manually ``````````````````````````` 1. Download the latest OpenMod.Unturned.Module-vX.X.X.zip from `openmod repository `_. 2. Copy the "OpenMod.Unturned" folder into the "Modules" folder inside the Unturned installation directory. 3. Start your server. The first start will take a while since OpenMod will download its core components. 4. Done! Now you can `start installing plugins `_. Plugins ------- You can find open-source OpenMod plugins `here `_. Resources ````````` - `GitHub Repository `_ - `Documentation `_ RocketMod Compatibility ``````````````````````` OpenMod can be installed side-by-side with RocketMod, so you can use both RocketMod and OpenMod without any issue. OpenMod does not aim to replace RocketMod but to work with it together instead. ================================================ FILE: servers/port-forwarding.rst ================================================ .. _doc_servers_port_forward: Port Forwarding =============== .. note:: After the 3.23.14.0 update, port forwarding is no longer necessary to make a server accessible over the Internet. It's only required if you want players to be able to join directly by IP and/or domain name. For more information on the new alternatives to port forwarding, please refer to :ref:`Server Codes ` and :ref:`Fake IP `. When hosting a server on a home network **port forwarding** is required in order to direct traffic to the host computer. One way to think of it is that when there are multiple devices (e.g. computers and phones) connected to the LAN, the outside Internet does not know which device is the Unturned server. In this case port forwarding specifies which LAN device is the host. Two pieces of information: the port range and local device address are required prior to port forwarding, and are described in detail below. Port Range ---------- Each Unturned server uses two consecutive ports while running. The first is for server list queries, and the second for in-game traffic. By default 27015 and 27016 are used. Setting a different value with the ``Port`` command uses that value and plus one. Recommended ``Port`` command settings are 27015 for the first server, 27017 for the second server, 27019 for the third server, so on and so forth. Local Device Address -------------------- Forwarding the ports directs them to a LAN address, i.e. the computer hosting the server. To determine the local IP on Windows: 1. Press Windows + R to open the Run dialog. 2. Type ``cmd`` and press enter. 3. Type ``ipconfig`` in the command prompt and press enter. 4. Find the ``Wireless LAN adapter Wi-Fi`` or ``Ethernet adapter Ethernet`` header. 5. Look for the ``IPv4 Address`` value and make note of it. This is the local address to forward the ports to. It likely looks something like ``192.168.0.6``. How to Forward Ports -------------------- Instructions vary by router, but should be doable from the web browser without any extra tools or software. This third-party website has a thorough list of routers with simple steps for each model: https://portforward.com/router.htm In general the steps are along the lines of: 1. Connect to router via web browser. 2. Login with home admin credentials. 3. Find Port Forwarding menu. 4. Find the option to add a new rule. 5. Name the new rule something related to Unturned for reference. 6. Input 27015 as the starting port(s) and 27016 as the ending port(s). .. note:: On some routers it might not be possible to input multiple ports within a single rule. In that case multiple rules can be setup; one for each of the two ports. 7. Enable UDP protocol. 8. Set destination internal IP to the local host address. 9. Save the new rule. ================================================ FILE: servers/rocket.rst ================================================ .. _doc_servers_rocket: Rocket ====== SDG maintains a fork of **Rocket** called the Legally Distinct Missile (or LDM) after the resignation of its original community team. Using this fork is recommended because it preserves compatibility, and has fixes for important legacy Rocket issues like multithreading exceptions and teleportation exploits. Installation ------------ The dedicated server includes the latest version, so an external download is not necessary: 1. Copy the Rocket.Unturned module from the game's Extras directory. 2. Paste it into the game's Modules directory. Resources --------- Browse the source code for the maintained version: `Legally Distinct Missile Repository `_. fr34kyn01535 has listed all of the original plugins in a post to the /r/RocketMod subreddit: `List of plugins from the old repository `_. The RocketMod organization on GitHub hosts several related archived projects: `RocketMod (Abandoned) `_ History ------- On the 20th of December 2019 Sven Mawby "fr34kyn01535" and Enes Sadık Özbek "Trojaner" officially ceased maintenance of Rocket. They kindly released the source code under the MIT license. `Read their full farewell statement here `_. Following their resignation SDG forked the repository to continue maintenance in sync with the game. On the 2nd of June 2020 fr34kyn01535 requested the fork be rebranded to help distance himself from the project. ================================================ FILE: servers/server-auto-restart.rst ================================================ .. _doc_server_auto_restart: Server Auto Restart =================== Server maintenance can be somewhat automated without plugins, by utilizing a couple features from your server's Config.json file. Scheduled Maintenance --------------------- We recommend restarting your server once every 24 hours, as much of the game's older code still uses single-precision floating point time. There are three settings for scheduled shutdowns: #. | **Enable_Scheduled_Shutdown**: When ``true``, the server will shutdown at a specified time. #. | **Scheduled_Shutdown_Time**: Local time for when the server will shutdown. #. | **Scheduled_Shutdown_Warnings**: Players will be notified via a chat broadcast at these times before the scheduled shutdown. For example, 30:00 will broadcast in chat 30 minutes before the shutdown. Checking for Updates -------------------- Your server can monitor for updates, and shutdown when one is detected. Three settings are important when checking for updates: #. | **Enable_Update_Shutdown**: When ``true``, the server will monitor for updates. #. | **Update_Steam_Beta_Name**: Defaults to ``public``, but can be set to ``preview`` for servers running on the preview branch. #. | **Update_Shutdown_Warnings**: After an update is detected, the server will wait for the longest of these durations to notify players before shutdown. For example, if the longest time is 2:30, the server will broadcast in chat 2 minutes and 30 seconds before the shutdown. Practical Application --------------------- These options are most useful in conjunction with a script that updates and restarts the server in a loop. For example, this Windows .bat script can be placed in the steamcmd folder to infinitely update and restart the server: .. code-block:: bat :linenos: @echo off rem @ suppresses echo command from being echoed, and then disables echoing in this script. rem This is a label for use with "goto". The script will return to this label to update and restart the server. :loop rem %~dp0 expands to the path to this script's directory, allowing it to be called from a different working directory. rem The "/wait" option pauses our script until steamcmd is finished. rem Start steamcmd, download latest version of Unturned Dedicated Server, then close cleanly. echo Updating... start "" /wait "%~dp0steamcmd.exe" +login anonymous +app_update 1110390 +quit echo Finished update! Launching server... start "" /wait "%~dp0steamapps\common\U3DS\Unturned.exe" -batchmode -nographics +InternetServer/MyServer echo Server has exited. Restarting after timeout... echo: echo Press CTRL+C and then Y during this timeout to cancel restart. timeout 10 rem Return to the "loop" label to update and restart the server. goto loop Here's a similar example for Linux, tested on Ubuntu. Note that the U3DS install path may be different depending how steamcmd was installed and whether ``+force_install_dir`` was specified, but typically one of these locations: 1. ``~/.steam/steam/steamapps/common/U3DS`` 2. ``~/Steam/steamapps/common/U3DS`` As such, it may be helpful to create a symbolic link to the U3DS directory: ``ln -s ~/.steam/steam/steamapps/common/U3DS ~/U3DS`` OR ``ln -s ~/Steam/steamapps/common/U3DS ~/U3DS`` This example script assumes the symbolic link exists at ``~/U3DS``. 1. Save script as ``MyServer.sh`` in your home directory (e.g., ``nano ~/MyServer.sh``): .. code-block:: shell :linenos: #! /usr/bin/bash while true; do echo Updating... steamcmd +login anonymous +app_update 1110390 -validate +quit echo Finished update! Launching server... cd ~/U3DS source ServerHelper.sh +InternetServer/MyServer echo Server has exited. Restarting after timeout... echo Press Ctrl+C during this timeout to cancel restart. read -t 10 done 2. Open a screen to run the server in with ``screen -S MyServer``. 3. Run script with ``bash MyServer.sh``. 4. If everything's working OK, press ``Ctrl + A`` then ``D`` to detach, leaving the script running. 5. You can re-attach to the screen with ``screen -r MyServer``. ================================================ FILE: servers/server-browser-curation.rst ================================================ .. _doc_server_browser_curation: Server Browser Curation ======================= This feature allows anyone to create and share lists of "rules" that filter or label servers in the server browser. Lists can be shared through the Steam Workshop as :ref:`Server Browser Curation Assets `, or automatically downloaded from a URL on the Internet. If you're a server host, suppose you want to prevent bad actors from copying your server details. Your first rule would ``Allow`` your genuine servers, for example, matching by ``ServerID`` ("server code"). Your second rule could then ``Deny`` servers with a regex that matches your server network's branding. - :ref:`Examples ` - :ref:`FAQ (Frequently Asked Questions)` Properties ---------- Name :ref:`string ` ::::::::::::::::::::::::::::::::::::::::::: Your display name in the user interface. For example, a server network might display as "MyNetwork Verified Servers", or someone creating a list of high-quality well-moderated hosts might choose "MyName's Recommendations". IconURL :ref:`string ` :::::::::::::::::::::::::::::::::::::::::::::: Optional URL of a 32x32 image to display in the user interface. For example, a server network might use the same icon they use in the server browser. Labels :ref:`list of dictionaries ` ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Labels applied by rules are defined here. Each has the following properties: **Name** :ref:`string `: Name used to refer to this label from a rule. **Text** :ref:`string `: Rich text displayed in the server browser. For example, defining two labels: .. code-block:: unturneddat :linenos: Labels [ { Name Verified Text MyNetwork Verified } { Name Fake Text MyNetwork Imposter } ] Rules :ref:`list of dictionaries ` :::::::::::::::::::::::::::::::::::::::::::::::::::::::: Rules are processed from top to bottom. Each has the following properties: **Action** *enum* (``Label``, ``Allow``, ``Deny``): ``Label`` applies a label and continues processing rules, whereas ``Allow`` and ``Deny`` both stop rule processing. ``Deny`` blocks the server, either hiding it or moving it to the bottom depending on the player's settings. .. note:: ``Allow`` and ``Deny`` **can** apply labels as well. The only difference is that ``Label`` action doesn't affect whether server is allowed or denied. **Inverted** *bool*: If true, negate whether this rule matches. i.e., binary NOT. **Description** *string*: Text shown in the rules list user interface and in the tooltip for servers moved to the bottom of the list. Please use this to document *why* your rule exists! **Label** *string*: Name of a label to apply. **Type** *enum* (``Name``, ``IPv4``, ``ServerID``): Determines which server data this rule matches against. - **Name**: Match server's name using one or more `regular expression (regex) `_. Refer to **Regex** or **Regexes** property. - **IPv4**: Match server's public IP using one or more `CIDR addresses `_. Refer to **Filter** or **Filters** property. - **ServerID**: Match server's ID (also referred to as "server code" or Steam ID). Refer to **Value** or **Values** property. **Regex** *string* or **Regexes** *list of string*: The rule matches if any of the regexes match the server name. (binary OR) One quick way to test a regex is to prefix it with "regex:" in the server browser name filter to search by regex. There are also a variety of helpful, free regex creation tools online. For example, matching any server with "MyNetwork" in the name: ``Regex (?i)(MyNetwork)`` (``(?i)`` enables case-insensitive matching) **Filter** or **Filters**: The rule matches if any of the rules match the server IPv4 address. (binary OR) IPv4 address with optional subnet mask and optional port number or range. Here's an example list with explanations: .. code-block:: unturneddat :linenos: Filters [ // Matches any port on this IP address. 10.8.0.1 // Matches port 27015. 10.8.0.1:27015 // Matches ports 27015 through 27030 (inclusive). 10.8.0.1:27015-27030 // Matches any port on IP addresses in the range 192.168.1.0 through 192.168.1.255. 192.168.1.0/24 ] **Value** *uint64* or **Values** *list of uint64*: The rule matches if any of the Steam IDs match the server's Steam ID. (binary OR) From the server console you can copy the server ID with "CopyServerCode". From the in-game server lobby screen you can copy it to the clipboard by pressing PageDown. .. _doc_server_browser_curation:examples: Examples -------- Here's a hypothetical verification list for the "NelsonNet" network: .. code-block:: unturneddat :linenos: Name NelsonNet Verification Example IconURL https://cdn.smartlydressedgames.com/ShareX/2024/12/ExampleIcon.png Labels [ { Name Verified Text NelsonNet Official } ] Rules [ { Action Allow Description Verify NelsonNet's Steam IDs Label Verified Type ServerID Values [ 85568392932910946 ] } { Action Deny Description Hide fake NelsonNet servers (case-insensitive check for "NelsonNet" in the name) Type Name Regex (?i)(NelsonNet) } ] For an example of adding a curator by web URL, here's the link for that list: ``https://cdn.smartlydressedgames.com/ShareX/2024/12/ExampleCurationList.txt`` .. _doc_server_browser_curation:faq: FAQ (Frequently Asked Questions) -------------------------------- How can I find the details for someone else's server? ::::::::::::::::::::::::::::::::::::::::::::::::::::: Pressing the **"Clipboard Debug"** hotkey (default **PageDown**) on the server lobby screen copies a variety of public information about the server to your clipboard. For example: .. figure:: /img/ServerInfoScreen.png An example server. Pressing the key on this server copies the following information to the clipboard: .. code-block:: text :linenos: Name: Nelson's PEI Server Description: Thumbnail: Address: 192.168.48.73 Connection Port: 27016 Query Port: 27015 SteamId: 85568392932910946 (k_EAccountTypeGameServer) Ping: 1ms 0 workshop file(s): Relevant details being: - Name (line 1) can be used in a **Name** rule. - Address (line 4) can be used in an **IPv4** rule. - SteamId (line 7) can be used in a **ServerID** rule. How do I create a regular expression (regex)? ::::::::::::::::::::::::::::::::::::::::::::: As a starting point, ``(?i)(your text here)`` matches "your text here" (without quotes) `case-insensitively `_. It would also match "Your Text Here" or "yOuR tExT hErE", but not "yourtexthere". For more advanced uses, we'd recommend using an online tool. At the time of writing (2025-02-07) these are top search results for "regex tool": #. https://regex101.com/ #. https://regexr.com/ #. https://regex-generator.olafneumann.org/ #. https://www.regextester.com/ ================================================ FILE: servers/server-codes.rst ================================================ .. _doc_servers_server_codes: Server Codes ============ A **Server Code** is a randomly generated, 17-digit numeric code assigned to your server. Your friends can join your multiplayer server by inputting its **Server Code** in the Connect Directly menu without you needing to :ref:`port forward `. Your server code can be found by clicking the "Copy Server Code" button while in your server. Alternatively, it appears in the Server Console immediately after your server finishes loading, and can be easily copied to your clipboard with the ``CopyServerCode`` command. Limitations ----------- The primary downside of Server Codes is their incompatibility with the pre-joining server info screen (which displays things like the server name, installed mods, current players, and other details). The info screen uses Steam's A2S protocol, which can only be queried by IP, so joining by Server Code enters the server immediately instead. You can enable :ref:`Fake IP` to work around this limitation. Your server's Server Code will change each time your server restarts. You can assign a :ref:`Game Server Login Token ` to keep your Server Code linked between sessions. How does it work? ----------------- Connecting by Server Code utilizes `Steam Datagram Relay (SDR) `_. To quote that page: *Relaying the traffic protects your servers and players from DoS attack, because IP addresses are never revealed. All traffic you receive is authenticated, encrypted, and rate-limited. Furthermore, for a surprisingly high number of players, we can also find a faster route through our network, which actually improves player ping times.* ================================================ FILE: servers/server-configuration.rst ================================================ .. _doc_servers_server_configuration: Server Configuration ==================== Most server options are found in your server's ``Config.txt`` file (e.g., ``Servers/Default/Config.txt``). If your server was created before **3.25.8.0**, please refer to the **How is Config.json converted to Config.txt?** and **Legacy Json File** sections. To check which options are overridden by your config you can add the ``-LogGameplayConfig`` command-line flag to print overrides to the console. Values left empty will use the default. They can be overridden by levels unless the ``-NoLevelConfigOverrides`` command-line flag is used. How is Config.json converted to Config.txt? ------------------------------------------- Servers created before **3.25.8.0** have a ``Config.json`` file rather than ``Config.txt``. The ``.json`` file stored options for each difficuly (easy, normal, hard), so during startup a per-difficulty ``.txt`` file is converted. For example, if the server ID is "ExampleServer" and difficulty is Normal (default), the file will be created at: ``Servers/ExampleServer/Config_NormalDifficulty.txt`` Only options changed from the default value are converted. This is because empty values in ``Config.txt`` indicate the default should be used. How can I change which config file is loaded? --------------------------------------------- You can override the config file path with the ``-GameplayConfigFile`` command-line option. For example, if your server ID is "ExampleServer", here's how to use this option: ``-GameplayConfigFile="SpecialEventConfig.txt"`` will create ``Servers/ExampleServer/SpecialEventConfig.txt``. Alternatively, you can provide an absolute file path like: ``-GameplayConfigFile="C:/SpecialEventConfig.txt"`` How can I remove generated comments? ------------------------------------ If you don't want explanations for each option in ``Config.txt`` you can add the ``-GameplayConfigNoGeneratedComments`` command-line flag. This removes all comments prefixed with ``>``. This is useful for a more concise config file. How can I remove unused options? -------------------------------- If you don't want all available options listed in ``Config.txt`` you can add the ``-GameplayConfigNoEmptyValues`` command-line flag. This removes all non-overridden options. This is useful for a more concise config file. How can I prevent levels from overriding my config? --------------------------------------------------- If you assign a value in ``Config.txt`` it will take priority over level overrides, whereas empty values (default) can be overridden by levels. To entirely prevent levels from overriding any config, you can add the ``-NoLevelConfigOverrides`` command-line flag. Legacy Json File ---------------- Older server folders have a ``Config.json`` file. During startup, the server will automatically convert it to the newer format according to the difficulty (easy/normal/hard). Downsides of the older format: #. Level overrides take precedent over default values. The server compares level config overrides to the values in the json file, and only overrides if it matches the default value. This means if you prefer the default (e.g., Hitmarkers ON) but the level turns them off it's not possible to prevent it without the ``-NoLevelConfigOverrides`` command-line flag. #. It contains easy, normal, and hard difficulty values in the same file. It's confusing to change a value but not have it apply because it's for a different difficulty level. #. Common to forget commas after values which breaks loading the file. #. No support for comments. Benefits of the newer format: #. All settings have comments explaining their use, options, and default value. Your own comments are preserved alongside the autogenerated ones. #. Separate files per difficulty, as well as the option for additional configs with the ``-GameplayConfigFile`` command-line option. #. Easier for new hosts because notepad can open it by default, and commas are not required. If you wish to continue using the ``Config.json`` file instead of the newer file, you can add this command-line flag: ``-UseLegacyJsonGameplayConfig`` ================================================ FILE: servers/server-hosting-rules.rst ================================================ .. _doc_server_hosting_rules: Server Hosting Rules ==================== Server hosts are able to customize their server in order to offer a tailored gameplay experience to their players. This often includes adding new features, disabling vanilla content, or using custom rulesets. However, all servers must adhere to the rules outlined below. Servers that violate these rules may be temporarily or permanently banned. To report a server for rule violations, or appeal a moderation decision applied to your server, you may file a ticket with SDG Support: * `Report a server for breaking rules `_ * `Appeal a server report `_ `View Moderation List `_ Recent changes -------------- **2025-06-12:** Clarified what counts as a "vanilla premium content" and what servers are allowed to do instead. (Previously, this was only detailed in the "Recent changes" section.) **2024-06-03:** Scaled back the degree to which the server list is moderated. The previous level was untenable especially when considering anyone can freely create an unlimited number of servers, and the moderation system is duct-taped on top of the otherwise unmoderated Steam server list. For more information, please refer to our `support article about moderation and server curation as well as some behind-the-scenes details `_. Monetization Types ------------------ Servers are not allowed to sell or otherwise offer access to **vanilla premium content**. This includes the Gold Upgrade benefits in addition to any vanilla cosmetics and/or skins. For example, any item purchasable from the Stockpile or the Steam Community Market for Unturned is considered a "vanilla premium content". When offering cosmetic perks to players as a microtransaction, the server should own (or have licensed) the rights to that content. For example, you could create your own custom "cosmetics" and offer those to players instead. Monetization Filter ------------------- Players can filter the in-game server list by this field. It is not required to configure this field, but ideally it should be set to whichever value accurately describes your server's monetization practices. When configured, this field must be configured truthfully. ``Unspecified`` ``````````````` The "Monetization" field in each :ref:`doc_servers_server_configuration` file defaults to ``Unspecified``. If you are unsure what to configure your server's monetization type as, then you can leave it unspecified. ``None`` ```````` Servers that are entirely unmonetized, or only offer a donation option, can use the ``None`` value. ``NonGameplay`` ``````````````` Servers that only offer microtransactions that do not provide a gameplay advantage can use the ``NonGameplay`` value. For example, selling custom weapon skins and chat colors would not be a gameplay advantage. ``Monetized`` ````````````` Servers that offer *any* "pay-to-win" microtransactions (i.e., those that provide a gameplay advantage)—such as selling "kits" containing items or vehicles—should use the ``Monetized`` option. Online Conduct -------------- Repeat violations of `Steam's Online Conduct rules `_ by a multiplayer server may result in moderation. For example, servers that exist to promote the sale of cheats are not allowed. If you encounter inappropriate behavior by *other players* while playing on a server, we encourage you to report it to the server's owner first so they are aware of the issue. Roleplaying Current Events -------------------------- Simulating gameplay of current, real-world tragedies is **not** allowed and may result in reduced visibility or other moderation on the server. For example, roleplaying ongoing conflicts (such as the the Russo-Ukrainian War, or Israeli-Palestinian conflict) or natural disasters. Anycast Proxies --------------- If you use an anycast proxy, please consider `submitting a support request here `_ to ensure it is flagged correctly. Otherwise, players will almost certainly report the server. Anycast proxies are a great protection mechanism, but they significantly affect the ping reported in the server browser. For example, a server hosted in Australia may have a ping of 40ms for players in the region but a ping of 300ms for players in Europe. Using an anycast proxy, in this case, would report a much lower ping (e.g., ~30ms) to players around the globe and incorrectly sort the server among those with the lowest ping. This is frustrating for players looking for low-latency servers, as they may join one with a low ping only to find it is much higher in-game. Servers using an anycast proxy are flagged to sort like they have a higher ping to avoid this problem. It was implemented as a direct response to complaints from players. Servers using a regular proxy with ping similar to the actual in-game ping are not flagged. Only proxies with a significant ping difference are flagged. Workshop File Copyright Infringement ------------------------------------ Mod authors can submit a notice of copyright infringement here: https://steamcommunity.com/dmca/create/. These are reviewed directly by Steam's copyright agent. FAQ (Frequently Asked Questions) -------------------------------- Can I report servers for admin abuse or pay-to-win features? ```````````````````````````````````````````````````````````` This is not reportable. Unfortunately, the best option is to play on a different server, or to :ref:`host your own multiplayer server ` for you and your friends. Moderating individual community servers is not tenable at our current small scale with current tools, but may be revisited if/when it becomes feasible. How can my server mitigate Denial of Service (DoS) attacks? ``````````````````````````````````````````````````````````` If your server is receiving DoS attacks, the :ref:`doc_servers_fake_ip` feature is a great way to protect against this behavior. It routes traffic through Steam's relay network, shielding your server's IP, and potentially reducing network latency for players. How can I prevent people from re-uploading my Workshop files? ````````````````````````````````````````````````````````````` Update your mod to include an :ref:`doc_asset_bundle_custom_data` and configure it to use the original upload's Workshop file ID. This adds a verification check to when a server attempts to download the mod – preventing it from being downloadable if the mod's Workshop file ID doesn't match the configured value. As a last resort, if your content has been reuploaded to Steam by another user without your permission, you may consider submitting a `notice of copyright infringement `_. Notices of copyright infringement are reviewed by Valve's copyright agent, and should only be submitted if you understand the legal information on their submission page. ================================================ FILE: servers/server-hosting.rst ================================================ .. _doc_server_hosting: Setting up a Server =================== Players can host their own multiplayer servers through the **Unturned Dedicated Server** tool. (This can be abbreviated as "**U3DS**".) This tool is provided alongside Unturned but must be installed separately. It can be installed and ran from your Steam Library, or instead through :ref:`SteamCMD ` for a much more advanced setup. .. figure:: /img/U3DS_SteamLibrary.png Find the **Unturned Dedicated Server** app in your Steam Library. Servers can be hosted on Windows and Linux operating systems. There is no support for hosting on macOS devices. .. _doc_server_hosting:simple_setup: Simple Setup ------------ This section provides a quick guide to creating your own server—perfect for hosting a *private* multiplayer world for just you and a few friends. Port forwarding and other optional – *but useful* – features are not covered in this section. Consider reading more advanced setup instructions once your server is functional. 1. Launch the Unturned Dedicated Server app ``````````````````````````````````````````` Launch the **Unturned Dedicated Server** app from your Steam Library. The Server Console will open in a new window. It may take a few minutes for your server to boot up while it generates any necessary files and loads your world data. .. figure:: /img/U3DS_LoadingLevel.png You should see "Loading level: 100%" when it finishes booting, along with a :ref:`Server Code `. 2. Invite your Friends `````````````````````` You can invite players to your server through your Steam Friends List. Players can also join your server by using the 17-digit **Server Code** created when you opened your server. This randomly-generated code will change each time you launch the server. It can found be clicking the "Copy Server Code" button while in your server, or by copying it from your Server Console. .. hint:: Players—including yourself—can join your server by inputting the server's **Server Code** in the **Connect Directly** menu. For friends, it's often quickest to just invite them through Steam! By default, your server is not visible to others from the Multiplayer menu unless they are on the same LAN connection. Without following more advanced setup instructions, this *functionally* means that players can only join via your Steam Friends List or if you share the Server Code with them. Save and Shutdown ----------------- There is no built-in autosave feature. You must use the ``Save`` command to manually save your server while its still running, or the ``Shutdown`` command to safely save and close your server. Savedata and configuration files can be found in the ``...\U3DS\Servers\`` directory. You will see a folder for each server you have created. .. _doc_server_hosting:configuration: Configure Server Settings ------------------------- Configuration files can be found inside your server's server folder. Most settings cannot be configured while the server is open. .. hint:: If you created a server using the :ref:`Simple Setup ` guide, you can find your server's settings from the ``...\U3DS\Servers\Default\`` directory. Commonly-used configuration files are: - | **\\Server\\Commands.dat** – Configure basic server settings, such as: Map, Password, and Max Players. - | **\\Config.txt** – Adjust difficulty settings and advanced server settings, such as: increasing Item Spawn Chance or assigning a Game Server Login Token. (see :ref:`doc_servers_server_configuration`) - | **\\WorkshopDownloadConfig.json** – Download mods from the Steam Workshop. Commands ```````` Commands—sometimes referred to as console commands or cheat commands—range from tweaking server settings to spawning items. Most commands are set in the **Commands.dat** file, with each command separated by a newline. Learn more about available commands on the `Unturned Wiki `_. Below is an example setup that includes many commonly-used commands: .. code-block:: unturneddat // [[ SERVER CONFIGURATION ]] // Lines starting with "//" are comments – which aren't read when launching your server. // Read more about commands on the game's wiki: https://unturned.wiki.gg/Commands // Name of your server in the server list. Name My Unturned Server // Specify which map to load, by name. // Official maps include PEI, Washington, Yukon, Russia, and Germany. // Use the WorkshopDownloadConfig.json file to download Workshop maps. Map PEI // Maximum number of players that can be on the server. MaxPlayers 24 // Assign a player's steamID64 as the "Owner" to give them administrator privileges, such as invoking cheat commands while in-game. // Owner YourSteamID // Enable "cheat commands" for administrators, such as spawning items or vehicles. Cheats // Require a password to join the server. // Password ExamplePassword1234 // Disable player-versus-player combat. // PvE // Limit players to a certain camera perspective, such as only first-person. By default, players can use both first-person and third-person perspectives. // Perspective First // Perspective Third Perspective Both // Perspective Vehicle // Which port should be used when port forwarding. // Port 27015 Runtime ~~~~~~~ Some commands only work during runtime. For example, the ``Save`` command only works while the server is running. You can use runtime commands in two ways: a. Type them into the **Server Console**. b. From the **in-game chat** (only if you are an administrator) while prefixing them with ``@`` or ``/``. .. tip:: Add your Steam ID as an administrator (a) via the ``Owner`` command, (b) by using the ``Admin`` command during runtime, or (c) by including it in the **Adminlist.dat** file. Use the ``Help`` command to either view a list of *all* commands, or describe a specific command. Some runtime commands require ``Cheats`` to be enabled. For example, ``Give`` is a cheat command used to spawn items. Learn about more commands on the `Unturned Wiki `_. Difficulty Settings ``````````````````` Configure your server's game rules, public server listing, and many other options from the :ref:`doc_servers_server_configuration` file. By default, there are separate config files for each difficulty preset – Easy, Normal, and Hard. By default, servers use the Normal difficulty file. .. hint:: You can use the ``Difficulty`` command to use the settings configured in either the Easy or Hard files. Steam Workshop Mods ``````````````````` Use the **WorkshopDownloadConfig.json** file to install mods from the Steam Workshop for use on your server. Players attempting to join your server will automatically download any mods configured in this file! 1. | Open the **WorkshopDownloadConfig.json** file. 2. | Find a mod on the Steam Workshop and copy the **File ID** in the URL. For example, the `Hawaii `_ map. .. code-block:: text URL: https://steamcommunity.com/sharedfiles/filedetails/?id=1753134636 File ID: 1753134636 3. | Add the File ID to the **File_IDs** list. Example: .. code-block:: json "File_IDs": [ 1753134636 ], .. tip:: You can add multiple mods by separating each File ID with a comma. Example: .. code-block:: json "File_IDs": [ 1753134636, 1702240229 ], 4. During server startup, any specified mods (and their dependencies) will be installed and updated. Players will automatically begin downloading any mods while connecting to the server. Curated maps—and a few official arena maps—are only accessible via the Steam Workshop. Like other mods, they need to be downloaded by the server in order to be used: .. csv-table:: :file: /img/WorkshopMapIDs.csv :widths: 30, 70 :header-rows: 1 .. _doc_server_hosting:internet_server: Switching to an Internet Server ------------------------------- Servers are hosted as a **LAN server** by default. This means players can only join when invited through your Steam friends list, or by using your randomly-generated Server Code. LAN servers are *not* visible from the Internet server list. There are a couple options for switching from a LAN server to an **Internet server**. .. attention:: Internet servers should follow our :ref:`Server Hosting Rules `. Get started by adding a :ref:`Game Server Login Token ` (GSLT). This login token is necessary when hosting an Internet server. Configuring it also means your Server Code will no longer change each time you launch your server. For an Internet server, you must configure either :ref:`Fake IP ` or :ref:`Port Forwarding `. Configuring both is **not necessary**. Fake IP is easier to enable, and it should be adequate for most servers. Related Topics -------------- Some servers may benefit from a more advanced setup than the one provided in our :ref:`Simple Setup ` guide. Chiefly: - :ref:`Use SteamCMD ` to host multiple servers at once. - Install plugins through frameworks like :ref:`Rocket (LDM) ` or :ref:`OpenMod `. ================================================ FILE: servers/server-update-notifications.rst ================================================ .. _doc_server_update_notifications: Server Update Notifications =========================== Change logs are available on the `Steam News Hub `_. For quick notifications with the game version number and Steam build ID consider one of the following: Discord ------- Messages are posted to the #dedicated-server-updates text channel on the `Official Discord Server `_ via web hook. Each message has fields with the game version number and Steam build ID. RSS --- Each release is posted to an RSS feed on the Smartly Dressed Games website, with the game version number and Steam build ID: https://smartlydressedgames.com/rss/unturned-steam-dedicated-server-updates.xml ================================================ FILE: servers/steamcmd.rst ================================================ .. _doc_steamcmd: Using SteamCMD (Advanced Setup) =============================== Some servers may benefit from a more advanced setup than the one provided in our :ref:`Simple Setup ` guide. This page assumes you have read the full ":ref:`Setting up a Server `" documentation. When hosting multiple servers at the same time, we recommend using `SteamCMD `_ to install the **Unturned Dedicated Server** tool rather than installing it from your Steam Library. SteamCMD is a command-line version of the Steam Client. It is not possible to run multiple servers at once—from the same computer—*without* using SteamCMD. Servers can be hosted on Windows and Linux operating systems. There is no support for hosting on macOS devices. Download SteamCMD on Windows ---------------------------- Installation on Windows operating systems (such as Windows 10 or Windows 11) is very straightforward. 1. `Download `_ SteamCMD for Windows. 2. Extract the contents of the zip to somewhere you can find it again. 3. Run ``steamcmd.exe``. Download SteamCMD on Linux -------------------------- Installation on Linux varies by distribution and your admin preferences. We recommend referring to `Valve's Linux Documentation `_. Once downloaded, run the ``steamcmd.sh`` script. Install the Unturned Dedicated Server with SteamCMD --------------------------------------------------- 1. | Login to Steam anonymously. .. code-block:: shell login anonymous 2. | Download the Unturned Dedicated Server application. .. code-block:: shell app_update 1110390 .. tip:: This command can also be used to update the Unturned Dedicated Server. 3. | Close SteamCMD once the download finishes. .. code-block:: shell quit 4. | In your SteamCMD folder, the server files can now be found within the default app install directory. For the Unturned Dedicated Server, this is ``.../steamapps/common/U3DS/``. If you need additional information, consider reading the SteamCMD wiki page's "`Downloading an App `_" section. Launch a Server on Windows -------------------------- Although old, this video guide remains fairly accurate and can supplement the reading below: https://www.youtube.com/watch?v=8axVrnSLlx4. 1. | Navigate to your server files. When using the default app install directory, these should be found at ``...\steamcmd\steamapps\common\U3DS``. 2. | Create a new text file within the U3DS directory. This file can be named anything – but for the purposes of this guide, we will call it "**MyServer**". 3. | Change the file type from a text file (.txt) to a batch script file (.bat). To do this, simply edit the file's name and replace the ``.txt`` file extension with ``.bat``. For example, "**MyServer.bat**". .. warning:: If the file name does not display the ``.txt`` file extension – e.g., you see "MyServer" rather than "MyServer.txt" – you need to enable the viewing of "File name extensions" in Windows. Click the "View" button in File Explorer and enable the "File name extensions" option. Once enabled, you can see and edit file extensions as part of file names. .. image:: /img/FileNameExtensions.jpg 4. | Open **MyServer.bat** in any text editor, such as Notepad. 5. | Copy-and-paste one of the following scripts into the file, depending on the type of server you are hosting: For an **Internet** server: .. code-block:: batch start "" "%~dp0ServerHelper.bat" +InternetServer/MyServer For a **LAN** server: .. code-block:: batch start "" "%~dp0ServerHelper.bat" +LanServer/MyServer .. tip:: In the provided scripts, "MyServer" is being used as the ServerID. Your server's savedata and configuration files will be found in a folder named after your chosen ServerID. **ExampleServer.bat** is an example of a LAN server. Opening it in a text editor will provide additional information that may be helpful should you need it. 6. | Save your changes to the file and close it. 7. | Double-click **MyServer.bat** to launch your server. A command-line interface should appear. Since this is the first time you have launched your server, it will need to generate your server's configuration files. .. image:: /img/InterfaceU3DS.jpg 8. | You should see "Loading level: 100%" when the server has finished loading (and generated all necessary files). Use the ``Shutdown`` command in the command-line interface to safely save and close your server for now. 9. | Your server's configuration files can be found in a newly-created folder (named after its ServerID) within the ``...\U3DS\Servers`` directory. This is where your savedata and configuration files are stored. .. tip:: Refer to :ref:`Setting up a Server – Configure Server Settings ` for guidance on customizing your server. 10. | When hosting an Internet server, refer to :ref:`Setting up a Server – Switching to an Internet Server ` for guidance on adding a :ref:`Game Server Login Token ` and using either :ref:`Fake IP ` or :ref:`Port Forwarding `. Once configured, you can open your server by running the **MyServer.bat** script! Launch a Server on Linux ------------------------ 1. | Navigate to your server files. When using the default app install directory, these should be found at ``.../steamcmd/steamapps/common/U3DS``. 2. | Copy-and-paste one of the following commands into your Linux terminal, depending on the type of server you are hosting: For an **Internet** server: .. code-block:: batch ./ServerHelper.sh +InternetServer/MyServer For a **LAN** server: .. code-block:: batch ./ServerHelper.sh +LanServer/MyServer .. tip:: In the provided scripts, "MyServer" is being used as the ServerID. Your server's savedata and configuration files will be found in a folder named after your chosen ServerID. **ExampleServer.sh** is an example of a LAN server. Opening it in a text editor will provide additional information that may be helpful should you need it. 3. | You should see "Loading level: 100%" when the server has finished loading (and generated all necessary files). Use the ``Shutdown`` command in the command-line interface to safely save and close your server for now. 4. | Your server's configuration files can be found in a newly-created folder (named after its ServerID) within the ``...\U3DS\Servers`` directory. This is where your savedata and configuration files are stored. .. tip:: Refer to :ref:`Setting up a Server – Configure Server Settings ` for guidance on customizing your server. 5. | When hosting an Internet server, refer to :ref:`Setting up a Server – Switching to an Internet Server ` for guidance on adding a :ref:`Game Server Login Token ` and using either :ref:`Fake IP ` or :ref:`Port Forwarding `. Once configured, you can open your server by running the **MyServer.sh** script! Related Topics -------------- Some additional topics are covered elsewhere. Of particular interest: - Install plugins through frameworks like :ref:`Rocket (LDM) ` or :ref:`OpenMod `. - Automate server maintenance with :ref:`Server Auto Restart ` features. - Configure a :ref:`Bookmark Host ` so players can "Bookmark" your server. - :ref:`Stay notified ` when the Unturned Dedicated Server app has an update.