Making-your-first-model.md

+# Model
+Model Engine needs model files to display them in game. It is designed to work seamlessly with [BlockBench](https://blockbench.net/), which is a free software that can be used for modeling, texturing, and animating. 
+> Note: This page does not focus on explaining how to use Blockbench or texturing. Please watch or read a tutorial online for that.
+
+To start modeling, create a new Generic Model project or Bedrock Model project (Generic is recommended) in the start page. And fill in `File Name`. `File Name` would be the ID of the model in Model Engine, so choose wisely.
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/create_project.png)
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/create_project_2.png)
+
+Before moving any further, there are a few very essential concepts you must learn.
+
+## Bones and Cubes
+When modeling, it is important to know the differences between `Bones` and `Cubes`.
+
+Cubes are each individual cube in a model. Bones are folders for cubes, grouping them up. 
+Model Engine achieves smooth animation by taking a Generic or Bedrock model and splitting it into multiple resource pack compatible models, based on the bones. In-game every bone is represented by an armor stand that wears the new models on its head.
+
+Because the new models are put into a resource pack, `Cubes` must obey the laws and restrictions of Minecraft Item Modeling:
+* Rotations can only be 0, 22.5, -22.5, 45, and -45. Rotations like 90 and 67.5 do not count.
+* Only one axis can have a rotation
+* Cannot be larger than 112x112x112 pixels, or 7x7x7 blocks (technically 3x3x3 blocks, but Model Engine uses display sizes to work around it)
+> Note: You can hold shift while rotating to restrict your rotation values, however, they can still become illegal. Personally, I (Flame) like to create my model in Blockbench's Block/Item Project because it automatically keeps the rotations legal, then imports them into Generic Project.
+
+However, `Bone` has less restriction:
+* Can rotate with no limits
+* **Cannot be larger than 112x112x112 pixels (To make a model larger than this, combine bones together using parenting.)**
+
+You can build the entire model with only bones, but since each bone with a model represents an armor stand, it is wise to keep a balance between `Bone` and `Cube`. bones that don't contain any model are considered `Virtual Bone`s, and don't have armor stands.  
+
+In Blockbench, you can create a `Bone` by adding a folder/group to the outliner. Then, you can start adding cubes into the bone.  
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/bone_and_cube.png)
+
+Let's make a simple humanoid model. Meet Kindletron JR.  
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/ME-Model-1.png)
+
+When modeling, make sure you look at the grid in Blockbench and see if your model is facing North. Model Engine uses North as the default forward direction. The grid is 16x16 pixels big, or 1 block big if you need a sense of scale.
+
+> Note: Conveniently, the grid is also exactly the ground level of Minecraft. If you want the model to be standing, make sure the feet are touching that grid!
+
+## Parenting
+No, this has nothing to do with teaching children.  
+Parenting is when one bone is placed inside another bone. The outside bone is the parent, and the inside bone is the child. This is useful because the child bone will follow the parent bone while [animating](https://github.com/Ticxo/Model-Engine-Wiki/wiki/Everything-about-animating) the model.
+
+It is a nice practice to create a parent-child bone hierarchy, so that when animating, bones will stay at the correct position.  
+Usually, bones are paired according to their connection. For example, connecting `Arm`(child) to `Body`(parent) so that `Arm` will stick to `Body`, no matter how `Body` moves or rotates.
+
+Let's do this to Kindletron JR. as well.  
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/ME-Model-2.png)
+
+## Pivot Point
+Each bone has a pivot point. It determines how the part rotates. For instance, the `Arm` bone should rotate near the side of the `Body` bone, so you place the pivot point next to the body. All bones should have a proper pivot point, or else they will rotate strangely when you animate it.
+
+You can set a bone's pivot point in BlockBench by selecting the pivot tool, then selecting the bone folder (NOT CUBE), and drag the pivot point.
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/ME-Model-3.png)
+
+## Head Rotation
+When mobs look around, the head turns before the rest of the body does. You can do this in Model Engine too!  
+All bones rotate like a body by default. If you want a bone to rotate like a head, all you need to do is find the bone, and add `h_` in front. Model Engine will interpret this as a head bone, remove the `h_` in the resource pack, and move this part like a normal head.  
+A model can have multiple head bones so you can create models with multiple heads. Head bone can also have child bones, but all child bones would also need the `h_` flag in front to act like a head.
+
+We can do this to Kindletron JR. too. I will set `head` bone as the head.
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/ME-Model-4.png)
+
+## Hitbox and Eye Height
+After creating the model, all there is left is assigning a hitbox and eye height to the model.  
+The `Hitbox` works exactly like how vanilla hitboxes do. You can hit it, shoot arrows at it, and the model will get stuck if trying to pass through a gap too small for it.  
+`Eye Height`, on the other hand, tells Model Engine how tall is the model. When a mob is short, it tends to look up at you. When it is tall, it looks down on you. `Eye Height` allows you to set the exact height of your model so the model looks at you correctly. It is also where the headshot area of the mob will be, so if blocked the mob will suffocate.
+
+Create both by adding a bone called `hitbox` with a cube inside. The size of that cube is the hitbox size, and the eye height is the Y value of the `hitbox` bone's pivot point.  
+Due to Minecraft's limitations, the X and Z values of the hitbox must be the same. Therefore, Model Engine only reads the X size of the cube, and ignores the Z size. The hitbox must also obey **Minecraft's hitbox limit, which is 64x64x64 in blocks (1024x1024x1024 in pixels)**.  
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/ME-Model-5.png)
+
+## Multi-hitbox
+R2.2.0 has a new feature that allows you to add sub-hitboxes to the model. They are like the normal hitbox mentioned above, but cannot collide with blocks and take suffocation damage. These hitboxes would act like bones and follow their parent, however, they will not rotate with the parent bone, and they must still be square-based.
+
+Create a sub-hitbox by adding a bone starting with `b_` and a cube inside. The size of the cube is the hitbox size. Same as the normal hitbox, it must obey Minecraft's hitbox limit, and X and Z values must be the same. 
+
+### Oriented Bounding Box
+R2.5.0 added a new type of bounding box for your sub-hitboxes. In Minecraft, basically all hitboxes are Axis Aligned Bounding Box, or AABB. These bounding boxes are easier to calculate, hence they cannot be rotated. Meanwhile, Oriented Bounding Box, or OBB, are AABB with the ability to be rotated. These hitboxes would act the same as normal sub-hitboxes, but they can rotate with the parent bone, and they can be any size.
+
+Similar to a normal sub-hitbox, create a bone with a cube inside, but the bone name starts with `ob_`, and unlike normal hitboxes, your cube can be any size you want, meaning the X and Z values can be different.
+
+## Driver & Passenger Point(s)
+If you want your mob to be controllable, you can set a specific location to mount on.  
+Create an empty bone named `mount` and place it wherever you like. The mount point can be animated, and if it is parented to another bone, it will follow the parent bone. Otherwise, it will follow the base mob.  
+>Note: In your mob's MythicMob code you'll want to add `drive=true` into your model spawning mechanic to enable mounting, then use Model Engine's `mountmodel` mechanic instead of MythicMob's `mount` mechanic for mounting the model. (Don't worry about this part until you get to coding!)  
+
+You can also create multiple passenger seats for other players/mobs to mount on. Unlike the driver seat, they cannot control the mount, and can have more than one point.  
+Create an empty bone and place it wherever you like, then add `p_` in front of the bone name. The passenger point can be animated, and if it is parented to another bone, it will follow the parent bone. Otherwise, it will follow the base mob.  
+>Note: Same as the driver seat, you should add `ride=true` in your model spawning mechanic, and use `mountmodel{driver=false}` to mount your entity.
+
+## Name tags
+To display the name of the model, or add an HP bar on top, you would need a name tag bone.  
+Each model can have as many name tag bones as you need. They don't need to be centered, and they can have animations.  
+To create a name tag bone, add `tag_` in front of the bone name.
+
+## Hand Item
+Sometimes you would like items to be synced in your model.  
+You can do so by creating a bone and add either `ir_` or `il_` to the front, which represents the right item and the left item respectively.
+> Note: The displayed item **IS NOT** displayed using the right and left hand, but rather the head slot. It might sound counter-intuitive, but this preserves animation accuracy.
+
+## Segments
+> Caution: This feature is still experimental. No animations would be played to segmented bones.
+
+The Destroyer from Terraria; Naga boss from Twilight Forrest; a centipede.  
+These are a few of many examples out there that require some sort of procedural animation to be realistic, and you can do so with segmented bone.  
+Convert a bone from normal to segmented by adding `seg_` in front of the bone name.
+
+## Saving Generic Project (Recommended)
+After creating a model, you'll want to save it of course! Make sure you are using the correct format.
+Save the model, texture, and animations by clicking `Files/Save Project`. It should be saved under the `.bbmodel` format.
+> ![](https://github.com/Ticxo/Model-Engine-Wiki/blob/master/wiki/modeling/exporting.png)
+## Saving Bedrock Project
+### **Deprecated. Last supported version: R2.2.0**  
+Save the model by clicking `Files/Save Model`. It should be saved under the `.json` format. It will want to have a .geo too, but it is unnecessary and should be removed. The texture can be saved by right clicking on it in the `TEXTURES` window and pressing `Save as`. The animations can be saved by going into the Animation tab and clicking `Animation/Save all Animations` You can also just press Ctrl+S to save all of these.
+
+That's it! You have created your first model!
\ No newline at end of file