GETTING STARTED WITH MODDING

========================

Please note that with the on-going development many things will change
and there is no guarantee that a future update will not break your mod.

OVERVIEW
--------

Each piece of custom content for Wreckfest is actually a folder in the game's
"mods" folder, with each folder representing a single mod. Mods can be easily
enabled and disabled individually by using an in-game mod manager interface,
accessible by the button on the main garage screen. Each mod folder should
have the same structure as the game's main data folder (so first subfolder
will be 'data') but only contain edited or new files. You can name the folder
as you wish. You should never modify files inside the game's core data as you
will otherwise lose the ability to easily disable modifications and possibly
trigger the anti-tamper system.

TOOLS
-----

* Bag Editor (in its own folder)

- Property editor for modifying various vehicle and other settings.
* bgeometry.exe
- Converts .bgo3 files to .scne and .vhcl files that the game uses.
* bimage.exe
- Converts .tga textures to game's internal .bmap image format.
* build_asset.bat
- A helper script which builds the given source texture (.tga) or
geometry (.bgo3) container using the above tools.
* wreckfest_vehicle_audio_tools.7z
- Example WWise project for creating your own vehicle sounds - see
the accompanying "Vehicle_audio_modding guide for Wreckfest.docx"
for more information.
* workshop/Uploader.exe
- Do not use directly, instead refer to the "Publishing Your Mod
to the Steam Workshop" section below.

VEHICLE MODDING WORKFLOW

------------------------

Follow these steps to get started on your first vehicle mod:

!!! IMPORTANT !!! You must first create a copy of the example car,
otherwise the next game update will overwrite your modifications.

1. Open Bag Editor.

2. Open "mods/example/data/vehicle/mod_vehicle_1/cameras.ccps".
3. Right Click on "mod_vehicle_1" folder.
4. Select "Folder Duplicate".
5. Give a name to your mod, for example "mods/my_mod/data/vehicle/my_vehicle",
6. Check "Copy non Bag Files" checkbox. This will enable copying files which
are not directly editable with Bag Editor, such as Art and Menu folders.
7. Click OK.
8. Now the necessary vehicle configuration files have been created.
You can access your modded vehicle inside the game by obtaning it from the
marketplace.

Use Bag Editor to modify your vehicle's parts and other properties. You can
also create new upgrade parts, located in the "part" folder. They will appear
in the game automatically, but you should pay attention that the parts are
parented correctly in relation to each other (see example parts for reference).

For texturing, edit the .tga textures in "art" folder and build them to .bmap
format using bimage.exe or build_asset.bat. If you want to add multiple skins
for your vehicle, use Bag Editor to create more .vepa files in "part" and/or
"paint" folder.

Icon for your car is located in "menu" folder. It should be 178x98 pixels in
size but inside a file that's dimensions are 256x128. The file name must also
end with "_178x98_raw.tga".

Vehicle geometry editing requires 3ds Max. An example body.max file is located
in "art" folder. The max file is exported to body.bgo3, which is then converted
to body.vhcl using bgeometry.exe or build_asset.bat.

IMPORTANT VEHICLE CONFIGURATION FILES

-------------------------------------

data/vehicle/my_vehicle/career/*.cavs

These are the vehicles which are drivable in game. Each .cavs file represents
a single vehicle that appears in the game, and you can have any number of
variants with the same or different assembly parts by simply creating new .cavs
files, naming them as you wish. The game searches for .cavs files located in
"career" folder.

Important properties:
- State: Must be "Mod" or "Disabled". Game ignores disabled vehicles.
- Flags: If "AI Vehicle" is checked, only AI Players can drive the
vehicle and it does not appear in the game's marketplace.
- Assembly: The parts from which the vehicle is assembled from. These are
the default parts that the vehicle contains when purchased.
AI vehicles will always use the parts defined here.

data/vehicle/my_vehicle/ai/player/*.aicr

These are the AI players which compete against you in the game.
The game searches for .aicr files located in "ai/player" folder.

Important properties:
- Vehicle: Which vehicle the AI player drives, refers to a .cavs file.
- Profile: How the AI player drives, refers to a .vaip file in "ai/profile".
- Paints: Which paint jobs the AI player vehicle may use. Upon event start
the game will randomly pick a paint from the list.

data/vehicle/my_vehicle/part/root.veru

Vehicle part upgrade tree root. MUST EXIST.

data/vehicle/my_vehicle/part
 This folder contains the parts from which vehicles are assembled from.
The game searches for all types of parts located in "part" and "ai/player"
folders.

Important properties:
- Upgrade: Configures how the part is used in the game.
- Upgrade/State: Must be "Mod" or "Disabled". Game ignores disabled
vehicles.
- Upgrade/Flags: If "AI Upgrade" is checked, only AI Players can use
the part and it's not visible in the game's marketplace.
- Upgrade Parents: Which vehicle, or another upgrade, can use this part.
Most parts are parented to "data/vehicle/my_vehicle/
part/root.veru", which means that any vehicle defined in
"data/vehicle/my_vehicle/career/*.cavs" can use the
part. Some parts are parented to other parts, for
example Engine Manifold (*.veem) is parented to engine
(*.veen), meaning that it can only be installed to
the engines listed in Upgrade Parents list.
- Upgrade Value: A reference to .upgv that is used to set, among other
things, part wear rate, durability and price. Note that
the price of parts is added to the vehicle price in the
marketplace, so if you want your vehicle to cost nothing
all part values will need to be set to 0.

data/vehicle/my_vehicle/part/tires

In .veti files, valid tire profiles are:

- standard_light
- standard_heavy
- racing_light
- racing_heavy
- rally_light
- rally_heavy

TRACK MODDING WORKFLOW

----------------------

Starting a new track roughly follows the same pattern as the vehicle workflow
above,
but please use "mods/example/data/track/exampletrack" as a reference instead.

IMPORTANT! Do NOT add your event to the list in "data/property/career/events.evss",

but always use .evst file inside your track folder instead.

The .tcat file (which contains trackside cameras) must have the same name as the
corresponding track .scne file.

3DS MAX 2015 PLUGIN/SCRIPTS INSTALLATION

----------------------------------------

1. Drag & drop Install_BugTools.mzp from tools/3dsmax into 3ds Max viewport.
2. In the installation dialog press the Browse button and locate Wreckfest.exe
from your "Steam/steamapps/common/Bugbear Entertainment" folder.
3. Press "Install BugTools" button and wait for the installation to finish.
4. Restart 3ds Max.
5. Exporter script can be found in "Customize User Interface" under BugTools
category. You can add hotkey for the script or drag it into the toolbar.
Script exports your scene to .bgo3 and builds it to your mods folder automatically.

PHOTOSHOP SCRIPTS INSTALLATION

------------------------------

1. Run Install_Bugbear_Exporter.bat from tools/photoshop folder

2. Type or paste your Photoshop script folder when asked (e.g.
"C:/Program Files/Adobe/Adobe Photoshop CC 2015/Presets/Scripts")

Script builds .bmap from .tga or .psd files (image needs to be saved
before you can export!). If you are exporting a .psd file, script saves
it to .tga (in the same folder as .psd) before exporting it.

PUBLISHING YOUR MOD TO THE STEAM WORKSHOP

-----------------------------------------

1. Create a preview image (.jpg or .png format, NOT .bmp) and place it in the root
of your mod folder (where your mod's "data" folder is located).
2. Open Bag Editor, right click any file inside your mod folder and choose "Mod
Publish".
3. A file called modinfo.modi is created for you if it does not already exist.
4. Fill in all the info fields but leave "Published Id" to 0 - the id will be
automatically assigned when publishing your mod. For now you can leave
"Visibility" as "Hidden" (default) and make your mod visible on the Workshop
page only when you're happy with it.
5. Click "Publish to Workshop" to launch an external tool which (as long as there
are no issues detected) will start uploading the mod to the Steam Workshop.
6. After a successful upload (it might take a while) the Steam Workshop page of
your
mod will automatically open and you can subscribe to your mod download it. Note
that when publishing your mod you need to accept the Workshop Legal Agreement
if
you haven't done so previously.
7. There will be a separate entry in the in-game mod manager for your Workshop
mod.

UPDATING YOUR WORKSHOP MOD

--------------------------

Launch the Mod Publish tool like the first time, update the info with the relevant
"Latest Change Note" but leave the "Published Id" field as it is and click "Publish
to Workshop".

!!! IMPORTANT !!! When creating and editing your mod always work with the files
in the game's "mods" folder and not directly those in the Steam Workshop folder.

!!! IMPORTANT !!! Note that if you have edited your mod description or other meta
data on your mod's Steamwork page they will be overwritten by what's in
modinfo.modi.