Gun Data Structure

1. Introduction

Gun Data (referred to as data from here on) is the complete set of parameters for a gun, compiled and packed into a single data file whenever it's saved from GDE; the main game then reads this file back to "recreate" the gun in a match.
Data is adjusted by the user through 2 methods
1. Entering it directly into the object in the Titan Engine Model Editor: these are usually fixed parameters that rarely change, like the gun's name, its details, how it operates, sound, etc.
2. Adjusting it in real time inside the GDE application: these are parameters that are hard to pin down by typing in numbers, needing continuous fine-tuning with high precision to find the best result, helped along by the application's tooling. For example: the gun's sensor, attachment position, attachment type, etc.

2. Directly entered information

Note: This kind of data is entered scattered across several different objects; this article is only meant as a listing, the step-by-step entry process will be covered in the Hướng dẫn section

Refer to the diagram below to quickly get a sense of the structure of this directly-entered data before diving into the details of each section

Cấu trúc thông tin nhập được cho vũ khí.canvas

2.1 Gun "body" object

The weapon model object, once imported into GDE, is named body. It's used for FPS view when only the CB pipeline is used, and doubles as the world model when the gun is dropped (has no owner), belonging to OBJ_GUN. It includes the following parameter groups:

2.1.1 AB group

anim base gun	- UID of the ABG model object - Can be left empty if the gun doesn't use the AB pipeline
anim base hand	- UID of the ABH model object - Can be left empty if the gun doesn't use the AB pipeline
anim base sound	- UID of the sound file used for the AB pipeline (not in use yet) - Can be left empty if the gun doesn't use the AB pipeline

2.1.2 Core stats group

attr cost	The gun's price, in Credits within the game
attr damage scale	- Scales the gun's damage up or down, higher values multiply the damage further. - Default value is 1, equivalent to the AK47's damage - Entering 2 would double this gun's damage compared to the AK47
attr draw delay	- Time from when the switch-weapon button is pressed until the gun appears on screen. - Measured in milliseconds - Only used by the CB pipeline - If AB replaces it, the draw time instead depends on the length of the corresponding animation
attr muzzle velocity	- The gun's muzzle velocity (in m/s). - Recommended to use the weapon's real-world figure if possible, e.g. the AK47 is 715 m/s
attr rate of fire	- The gun's rate of fire (in rounds/minute) - Recommended to use the weapon's real-world figure if possible, e.g. the AK is 600 rounds/minute
attr recoil	- The gun's base recoil; this value gets affected by several other factors before producing the final recoil that impacts gunplay - Default value is 0.07 - The larger the number, the more the gun kicks
attr recover time	- How long it takes the gun to settle back into its original position after each shot - Default value is 80ms. This is a fairly solid number that suits most guns, so it probably doesn't need tweaking. Feel free to adjust it to see the difference if you want.

2.1.3 Basic info group

basic author	Optional, can fill in the author's or team's name if needed
`basic gun code`	- This field is required - The code can be any string, meaningful or not, as long as it's unique. - Lowercase letters, no spaces. `ak 47` <- Wrong. Can crash the game - Usually kept short and based on the gun's name, like `ak47`, `m4a1`, `mp5a3`, etc., though it can also be something like `what_ever`, `myrandom_gun`, etc.
basic intro en	The gun's introduction text in English
basic intro vi	The gun's introduction text in Vietnamese
basic name en	The gun's name in English, e.g. AK-47, FN-2000, etc.
basic name vn	The gun's name in Vietnamese (usually the same as the English one)
basic version	This is optional, in case the user wants to tag a version for the weapon being created

2.1.4 CB group

This is a required group, it holds the intermediate objects that lead to deeper attributes.

code base gun anim	UID of the CBG's animation object
code base hand anim	UID of the CBH's animation object
code base reload duration	How long the CBG spends reloading (the CBG gets hidden from view during reload when not using the AB pipeline)
code base sound	UID of the CBG's sound object

2.1.5 Fire mode group (firemodes)

firemode burst double	Marks whether the gun has a double-burst fire mode (e.g. the AN94)
firemode burst triple	Marks whether the gun has a 3-round burst fire mode
firemode full auto	Marks whether the gun has a fully automatic fire mode
firemode single delay	Length in milliseconds for semi-auto; this parameter keeps players from clicking to fire rapidly with high-recoil guns like sniper rifles

2.1.6 Other parameters

gun built in suppressor	Marks whether the gun has a built-in suppressor (e.g. the MP5SD)
gun mag object	UID of the magazine object
gun max shell	For guns with a single-round loading mechanism, this is the maximum number of rounds the gun can hold, not counting the one already chambered
gun mechanic operation	Pick from the list of the gun's operating mechanisms, including: - Bolt action (`OPERATION_BOLT`) - Gas operation (`OPERATION_GAS`) - Pump action (`OPERATION_PUMP`) - Locked back action (`OPERATION_PISTOL`)
gun mechanic reload	Pick from the list of the gun's reload mechanisms, including: - Single insert (`RELOAD_SINGLE_INSERT`) - Magazine swap (`RELOAD_MAGAZINE`) - Stripper clip (`RELOAD_STRIPPER_CLIP`)
gun separated sight	- Marks whether the gun has a detachable ironsight (no built-in ironsight) - For this kind of gun, the ironsight mesh (rear sight and front sight) sits together with the CBG model and gets hidden once an optic attachment is mounted.
gun thumbnail image	UID of the gun's thumbnail image object
gun type	Pick from the list of weapon types the gun belongs to, including: - Assault rifle (`GUNTYPE_ASSAULT_RIFLE`) - SMG (`GUNTYPE_SMG`) - Pistol (`GUNTYPE_PISTOL`) - Sniper rifle (`GUNTYPE_SNIPER_RIFLE`) - Shotgun (`GUNTYPE_SHOTGUN`) - LMG (`GUNTYPE_LMG`) - Corner-shot (`GUNTYPE_CORNERSHOT`) - a special type with its own dedicated operating mechanism
gun viewoffset	- The gun's offset position when not aiming, default is `(0, 0, 0.13)` - This value is usually kept the same across every gun, but can be tweaked if needed

2.2 Objects for the AB pipeline

Both the ABH and ABG model objects each have their own smaller object holding their set of related animations. This object is named OBJ_ANIM_BASE_GUN_ANIM, shared by both models since they follow the same structure; the only difference is which animations go into it, depending on whether the model is ABH or ABG.

Refer to AB Pipeline Animation List for a more detailed description of each animation

OBJ_ANIM_BASE_HAND_ANIM includes the following animation groups:

Magazine-related group

magin
magin-dry
magout
magout-boltlock

Pose mount group

mounted
mounted-fire
mounted-fire-dry
mounted-fire-dry-boltlock

Pose normal group

normal
normal-fire
normal-fire-dry
normal-fire-dry-boltlock

Reload group

reload
reload-dry
reload-fast
reload-fast-dry

Other animations

weapon-deploy
weapon-in
weapon-inspect
weapon-out

2.3 Objects for the CB pipeline

Animation set for the CBG

See more details at Code-based and Animation-based > 3.2 Code-based Gun Animation

dry
original
shoot

Animation set for the CBH

See more details at Code-based and Animation-based > 3.1 Code-based Hand Animation

mounted
normal
normal-left
shield

Sound set
This object holds the collection of sound files a weapon can use. Note that these sound files follow a priority order and can substitute for each other depending on how much the user has prepared, specifically:

Outdoor > Indoor
1p > 3p
normal > suppressed

Priority example: if the indoor sound hasn't been prepared, the system falls back to the outdoor sound. The same logic applies to the other groups listed above.

The normal/suppressed pair also follows this priority mechanism, but since suppressed is a genuinely different sound, it should be prepared on its own, to avoid the gun playing its normal fire sound while a suppressor is attached.

List of sound slots

1p fire indoor normal
1p fire indoor suppressed
1p fire outdoor normal
1p fire outdoor suppressed
3p fire indoor normal
3p fire indoor suppressed
3p fire outdoor normal
3p fire outdoor suppressed
mag in
mag out
reload finish

2.4 Magazine and thumbnail

Some weapons don't use a magazine, but magazine information still needs to be present. This will be explained further in the tutorial.
The steps for preparing a standard-compliant thumbnail will also be covered in the tutorial.

3. Real-time adjusted information

This group of data isn't entered by typing numbers into an object's Param, it's adjusted directly in the GDE viewport instead, since these are all positions/sizes that are very hard to estimate accurately by typing alone, needing to be eyeballed and adjusted at the same time. It's all still saved together into the Gun Data file, same as the groups in section 2. How to adjust each of these points in GDE is covered in Modding Tools/GDE/Manual/Chế độ Gun Data Edit and Modding Tools/GDE/Manual/Chế độ Attachment Edit.

3.1 Anchor points on the gun

Some data points only apply to one specific pipeline, see the CB/AB columns

Data point	Role	CB	AB
Magazine position (`magPos`)	Where the detached magazine model sits on the gun. Not needed if the gun uses a single-round or stripper-clip loading mechanism	x
Muzzle	The gun's muzzle marker, used as the origin for effects and the bullet trajectory when firing	x	x
Butt	The gun's stock marker, at the rear of the gun	x
Shell position	Where the shell casing appears once ejected after firing	x	x
Shell eject direction	The direction the shell casing flies toward after being ejected	x	x
Sensor (Base and size)	A small marked-out area on the gun, made up of a center point and a size	x
ABG position offset	The offset used to align the AB gun model block with the gun's origin		x
AB Hand position offset	The offset used to align the AB hand with the gun		x

3.2 Attachment position and type per mount slot

Data point	Role
Mount type (Optic/Barrel/Muzzle)	Determines which attachment group is compatible and can be mounted into that slot
Attachment mount position	Where the attachment sits on the gun, stored separately per CB/AB pipeline since the two pipelines use different model spaces
Mount length	The length along the mount, used as the basis for computing the attachment's default position on that mount
Default position ratio	Where along the mount's length the attachment sits by default, before any further adjustment
Attachment rotation angle	The attachment's rotation around the mount's axis
Rail position (if any)	A separate mount position for the rail, distinct from the attachment's own mount position