Create creating-entities.md

Author: DeerTears

docs/entities/creating-entities.md

@@ -0,0 +1,169 @@
+---
+layout: default
+title: Creating Entities
+nav_order: 2
+parent: Entities
+---
+
+# Creating Entity Resources
+
+In Qodot, you define new types of entities by creating a new .tres resource file. Qodot provides 3 resource presets for this:
+
+- QodotFGDPointClass
+- QodotFGDSolidClass
+- QodotFGDBaseClass
+
+Click the "New Resource" icon in the Inspector:
+
+![](../images/res-inspector.png)
+
+Or right-click the FileSystem and click "Create New Resource":
+
+![](../images/res-filesystem.png)
+
+Either will take you to the resource search screen. Here you can type in the following quick terms to narrow down the type of resource you want to create:
+
+- pointclass
+- solidclass
+- baseclass
+
+# Point and Class Resource Properties
+
+These properties are shared by Point and Solid classes.
+
+**Classname** - The name for this class in Trenchbroom.
+
+**Description** - A short description that displays in Trenchbroom when this entity is selected.
+
+**Qodot Internal** - Hides the entity in Trenchbroom's entity browser.
+
+Qodot can still refer to this entity for building other entities (like base entities). Base Entities are already hidden in Trenchbroom by default, for most situations you can leave this off.
+
+**Base Classes** - An array of template entities to inherit properties from.
+
+This determines the parent entities for this class, where this entity gets all the class properties, meta properties, and property descriptions from its parents.
+
+**Class Properties** - A dictionary of properties.
+
+Once exported to the Trenchbroom game config, the dictionary values are written by editing entities in Trenchbroom, and read by accessing `properties` on a QodotEntity once the map is built.
+
+To add a new class property to an entity:
+
+1. Open the dictionary.
+2. Click the first pencil by "New Key: [null]" and select "String" as the key data type.
+3. Name your property in the key text field, no spaces.
+4. Click the second pencil by "New Value: [null]".
+5. Select any valid data type. Read [Class Property Data Types](#class-property-data-types) for more information.
+6. Change the value to your desired default, or leave it blank.
+7. Click "Add new key/value pair".
+8. Re-export your FGD once all class properties are added.
+
+You can also set default values for your properties, by repeating this process in Meta Properties, matching the key names and value datatypes from this dictionary.
+
+**Class Property Descriptions** - A dictionary of descriptions for each property, visible in Trenchbroom.
+
+Follow the same steps as adding class properties to add property descriptions. Ensure the description's key matches the property's key. Description values can only be strings.
+
+**Meta Properties** - Editor-specific properties, such as the default color and size used to represent this class.
+
+Add an entry with a matching key to an existing property, set the value to the same data type, and whatever value is present will become the default. Only one meta property is read per class property.
+
+**Node Class** - The type of Godot node to spawn at this location.
+
+This doesn't fully control the type of node that Godot spawns, read on to learn more about using Node Class with Point Classes and Solid Classes.
+
+## Point Class properties
+
+Point Classes inherit all features from Base Classes, with a few additions. QodotMap reads their position in the map, and places a QodotEntity node in their place. You have the option to replace the QodotEntity node with other node types, or even instance .tscn scenes in their place.
+
+**Scene File** - The .tscn Godot scene that spawns in place of QodotEntity. The easiest way to spawn a specific node at a specific point.
+
+Scene File takes priority over every other option here, especially if there's already a script attached to the .tscn file.
+
+**Script Class** - The script to attach to your entity's root node.
+
+This is ideal for spawning nodes without a .tscn file. If you want to access this entities' Class Properties, add a script here that `extends QodotMap` and accesses `properties["key_name"]`.
+
+You can extend other Spatial-derived node types too, and add necessary children (CollisionShape, MeshInstance) through code, but you lose out on the ablity to access `properties`. You can fix this by always choosing to extend `QodotEntity` and adding more complex nodes like Area and RigidBody as children through code.
+
+Make sure to update Node Class so it matches the the script's `extends`!
+
+**Node Class** - The type of node to spawn at this location. This property should match the `extends` of your Script Class. You can ignore this property if you're using a Scene File.
+
+With those properties covered, there's a few tricks you can use to get more specific results.
+
+If you want to create an RigidBody node without a .tscn using a point entity, extending `RigidBody` in thes script prevents you from accessing the class property values set in Trenchbroom. However, extending `QodotEntity` prevents you from accessing the functions and signals of a RigidBody.
+
+You can get around this by extending `QodotEntity` and using `var body = RigidBody.new()` and `add_child(body)` to add more complex nodes as children, while still having access to the `properties` dictionary. This can be repeated for other children like MeshInstance and CollisionShape.
+
+## Solid Class Properties
+
+Solid classes can have multiple brushes, so these properties apply to the solid class as a single object, not to each brush individually.
+
+**Spawn Type** - Changes how the QodotMap arranges these brushes in its node hierarchy.
+
+There are 4 settings:
+- Worldspawn
+- Merge Worldspawn
+- Entity
+- Group
+
+**Build Visuals** - Makes the solid class visible when checked.
+
+You may want to disable this for invisible triggers and other gameplay-related solid classes.
+
+**Node Class** - Sets the node type of the solid class root.
+
+If you're adding a Script Class, this value should match the `extends` of the script.
+
+Setting this to RigidBody and setting Spawn Type to Entity changes these brushes from static geometry into physics objects.
+
+**Collision Shape Type** - Changes how collision is built.
+
+- None
+- Convex
+- Concave
+
+Convex creations a CollisionShape for each brush, depending on the Spawn Type. Entity creates an outer hull, Group creates individual shapes for each brush. Convex is a good bet for most situations.
+
+Concave allows for concave brush geometry, or if you chose Entity and want a single concave CollisionShape to make up your solid class. 🚧
+
+**Script Class** - The script applied to the entity's root.
+
+Although `QodotFGDSolidClass` is a class you can extend from, this is meant as a Qodot internal to build solid classes. This does not extend QodotEntity, and will not give you access to `properties`.
+
+# Class Property Data Types
+
+As shown earlier in this page, you can define properties for entities in the Class Properties dictionary. The "key" for each dictionary entry should be a String. The "value" can only be one of these 8 data types:
+
+- Bool
+- Int
+- Float
+- String
+- Vector3
+	- Stored as a string in the form X Y Z
+- Color
+	- Stored as a string in the form R G B
+- Dictionary
+	- Used for defining a set of choice key strings and their associated values
+	- Will display a dropdown in compatible editors
+	- Available Dictionary value types haven't been thoroughly tested
+- Array
+	- Used for bitmask flag properties
+	- Will display a grid of checkboxes in Trenchbroom
+	- Used in Quake to indicate which entities spawn on different difficulties - easy, medium, hard
+	- Each entry in the array should be an array, with three elements: `[name: String, value: bool/float/int/String, default: same type as value]`
+
+## Note on Arrays
+
+When you add an Array as a class property, it must contain other Arrays, with each Array creating one flag. These flag Arrays must have 3 items: Name, Value, and Default value.
+
+Name must be a String.
+
+Value is traditionally a bool, but it can also be a float, int, or String. Qodot parses all these data types as Strings in the end, which will change how you will be [Accessing Class Properties in Code](#accessing-class-properties-in-code).
+
+The default value can be the previous data type, or even `null`. It is not read by Qodot, just the regular Value.
+
+# Accessing Class Properties in Code
+
+See [Scripting Entities](scripting-entities.md).