Creating a rideable animal/vehicle

I claim no responsibility if you break something XD -Cattrina 
This is very very WIP 
For a humanoid skeleton with a tail I recommend not adding new bones, as it breaks the sliders. Instead unlink the left hand prop bone and link it to pelvis. Naturally you will have to remake all 166 animations for the tail to move. (Credits to Kindrad). 
Click here for PDF with more data about the Sage Steeds: 
= About Skeletons and Portraits =
Edit 1: September 1st 2022: I have now tested and this setup works with the portraits without any issues. Edit 2: June 5th 2023 however this set up does not work with Kenshi's game engine. The main issue is the game uses hidden animation priorities to perfectly smooth the transfer from animation to animation, meaning it expects the 'back leg bones' to be named same as human legs. When they are new bones with new names the game do not understand them to be limbs, therefore several animations play simultaneously making the toter walk funny. Back to the drawing board. 
So make your toter's skeleton by adjusting the human skeleton. This naturally means you have to remake all animations, but you would have to do it anyways if you wanted to make a toter. Edit 2: Sept 2: Apparently it does not matter much where the photobooth bones are, if they are somewhat in the photobooth area, what matters more, is the location of the Bip01 bone. So you can move the horse forwards to have the front legs align with the center (from the image shown). 
== Rideable animals’ core issue. ==
There are two character types in Kenshi, humanoids and animals. They are treated differently by the engine. 
The biggest issue regarding riding, is the fact animals cannot pick up people.
So, I had to make a human, that looks like a bull.
== Whatthebull? Why so many problems with the Sage Steeds bulls? ==
Here a summary about the issues I encountered when making the Sage Steeds.
Using a non-humanoid skeleton where the game expects a humanoid skeleton, is the main cause for the following issues:
A) The sage steeds do not have a portrait.
B) The game crashes whenever the game tries to read the portrait file aka NPC talk to the bull. 
C) The bull's hull can be seen over the automatically generated building menu icons.
D) The bull's hull can be seen over small character's portraits.
The issue A is because the game expects a head mesh to be where the bull's hump is, so the ‘photobooth’ just takes a picture of empty air when the bull is kneeling and if standing the bull’s hull just covers everyone else.
The issue B is a direct result from A, this was originally ‘fixed’ by preventing all NPCs in a mod to NOT TALK to a dump personality. 
This caused a lot of issues as a dumb player character could not speak to NPCs. And modded-in NPCs someone else made, still wanted to talk to the bulls, hence crashing the game. I reverted this when introducing the fix. The game crash was fixed in version 6 by adding head bones to the bull's neck where the game expects them.
The issues C and D are the result of the game engine's problem to place the skeleton in its proper place in the game's inbuilt photobooth. Same reason as A, the game expects a humanoid skeleton and the bull’s hull does not fit in the booth and spills over to the furniture section. 
For some reason all the virtual photo booths are set in a check board like grid, right next to each other. So if I have a human on square 2-4 the chair on square 2-5 is fine. But the bull kneeling on 2-4 spills on square 2-5 and because the front is on an earlier square; the front covers the entire chair. Now, I do not claim to know this is exactly it. But makes it easier to understand what it is about (see image).
I really could not prevent the bull’s hull from overlapping the furniture, but making the idle animations kneeling, and all poses pulled back, I managed to barely avoid the human camera limits. The issue being all that mesh head and hump blocking the team mates’ portraits. I do not have a clue how this setup manages to not print all team mates’ images on top of each other always. I think the game might turn the skeletons in the exact same spot invisible, or something.
But knowing what I know, I truly recommend making a small vehicle, below chest level. Edit Sept 2022: Or make the toter roughly human sized, see the image I added at the top. At least try not to have anything going in front of the photobooth area( see that the head does not spill on 2-3).
= How to make your very own rideable non-humanoid skeleton =
You will need:
1)    Blender with Kenshi import/export plugin or Kenshi_IO_Continued plugin (the latter is better, but the first will suffice)
2)    Enormous amounts of time, patience and snacks… no double it!
For the purposes of this guide, I am referring to the animal or vehicle you are about to make as a ‘toter’.
== TIPS & FACTS ==
* Do all bone additions and renames to the skeleton BEFORE recreating the animations, as you will need to redo them every time you add or rename a bone. Think ahead. Is your toter needed to pull a cart? Add a bone for the cart from the beginning.
* If you are using a non-humanoid skeleton as a base, you need to grow identical bones for neck, head and headnub in the exact same position the humanoid skeleton has, to prevent the game crashing when a NPC tries to talk to the toter.  Use a humanoid skeleton as a reference but DO NOT COPY the bones, you need to GROW identical bones and rename them to fit. This also means the actual head neck and headnub bones the skeleton has, you need to rename something else. OR PREFERRABLY use the human skeleton and just add the back end bones.
* If the skeleton is larger than the humanoid skeleton, the hull will most likely overlap the toter’s teammate portrait pics. To compensate this, I made the bull to stay low when idle. The game keeps taking portraits so often, even a short time standing the bull’s hull would appear over every portrait. Consider making your toter stand lower than chest height if its hull is large.
* Do not mess with the bone link chain. Do not remove bones or cut the parenting link chain any way. This will result a non-exportable skeleton and you need to start all over. No, you cannot redo the chain. You would need to know the exact order the devs added the bones in the first place. Luckily you can ADD bones anywhere, if they do not need to be in the middle of two existing bones in sync. If they do, you might have to adjust the bone manually for every key frame in the animation. And I cannot guarantee the automated weights will work.
* Because the riding pose is the same pose as carrying, you will have to make a compromise on both. Also, your mod will overwrite all the above mods’ riding poses, so a subber can only effectively use one toter mod. Unless a community standard for a riding/carrying pose is used.
* If you are using the vanilla ragdoll, the hands of the rider will flap. The game nicely prevents other body parts from flapping, but the hands were designed to sway while carried. The gravity physics of the hands is down (from head towards hands) and when the character is posed upwards on a toter, the ‘wind’ created by going forward plays against the ‘gravity’ and this is why the hands flail. Removing the ragdoll completely fixes this, but then the character stays up standing when KOed. EDIT: I have managed to make a custom ragdoll, I am planning to make it a modder's resource after performance tests.
*Do not forget to export your custom skeleton with 'Apply Transform' selected. Otherwise the mesh may rotate in the game engine.
*You might have to also adjust the combat anatomy. But be careful, if the 'collapse part' (vanilla part) does not match the bones you listed, the game will crash. Same if you have not included all body parts or if you have too many. For a vehicle I think you could just keep the vanilla combat anatomy.
== How to add bones ==
=== The bone for rider on the toter's back ===
1)    Import the skeleton you want to add a carry bone to Blender
2)    Click on the skeleton and go to edit mode
3)    Select Add – Single Bone
 
4)    Move the bone where you want to place it. Do not rotate as it makes it more difficult for you to set the character pose. Click the bone, hold shift and click another bone on the bacj you wish the carry bone to follow, click Object and right-click and parent, make. I usually use offset. 
Do not adjust rotations. Make all animations first, do not save a keyframe for the carry bone. The rotations are unique for the skeleton you used as a base and relevant to the bone you chose as a link and to the carry me animation set up. 
Fe. If you are using my pose and the bull skeleton I made, the riding bone rotations are: 
5)    Navigate to the Bip01 L UpperArm and rename it fe. Bip01 L UpperArm 001 etc. Do notice the odd Bip01 BullNeck and BullHead bones. These were renamed after adding the ‘photobooth bones’ aka new set on human like neck, head and headnub bones.
6)    Make sure you have the ‘photobooth bones’ added and renamed (if you did not use human skeleton as base).
7)    Add any additional bones you need.
8)    Create animations for the skeleton. If it already had animations, save keyframes for each new bone you added and for the newly named Bip01 L UpperArm.001 bone. 
=== The entire linked bone-chain behind a male_skeleton (Sept 2022) ===
1) Import the human male_skeleton and optional 3d model reference of the animal shape, might be the final or something roughly similar.
2) Click the skeleton and edit. Create a new bone the same way as mentioned in the previous section. This will be your assistant bone.
3) Move the assistant bone roughly where you want the hind end of the future bone to be, do not rotate the bone.
4) Click a bone end on the human skeleton, hold shift and click an end of the assistant bone, hit F. This will create a bone LINKED to the human skeleton and it will follow the movements of the bone you chose. Might be easier to just pick the Bip01 as it does not move that much.
5) Move the assisting bone to next bone's position and link the end of the previous new bone to the end of the assistant bone.
6) Repeat step 5 until you have all the bones you need. Remember: The more bones a character has, the more burden on the game engine, so keep it as low as possible.
7) Give each new bone an unique name. Delete the assistant bone(s).
( 8) Create a weight group for each new bone. (Blender usually knows how to make weight groups automatically, but in case just rigging with automated weights does not work.) )
9) Rig the toter mesh to the skeleton. Select the mesh, hold shift, select the skeleton/armature and Object-Parent-Armature Deform with automated weights.
10) Now redo all weights to suit your model best. It will have odd deformities in the area where the humanoid bones are, I have not tested, but it should work if you just unweight all the human spine bones etc. Head (photobooth) bones should be weighted to the toter's actual head in this scenario.
= Animation =
The vanilla humanoid skeleton has 166 animations. For your toter to work, you need to make at least the mandatory animations to your skeleton (see name list below). They need to be named exactly the same, case and space sensitive. You might get issues if you are lacking the vanilla animation strip names, so do not delete strips, just empty them. 
If you decide to just have the humanoid skeleton there for the sake of expected bone names and animations, then you really only need to edit the animations where the head/photobooth bones move + the movement animations like walk, jog, run, sit etc. And you could leave untouched such animations that the toter does not need. Which would mean nothing would happen when such animation were called by the game engine. Frankly, I would still prefer a copy of the Stand 1 written over the futile anims, so at least the character would not pause in weird pose mid-action.
The game knows how to pause main animation file action for the vanilla bones, but for any added bone you must manually make sure the main animation has keyframe for that bone, and the co-animation does not (unless it is an expressive bone). Also the Extrapolation, Blending and Influence have affect on non-vanilla bones. The game handles those for vanilla bones, but for any additional bone you need to set these in Blender.
Do not forget to make an animation file in FCS for your toter and add(assign) it in the race file using the pull down menu.
 See a YouTube video of cart wheels turning
== Vanilla Animation Names List ==
Mandatory animations are in bold (game breaks or crashes without). You can of course just have a 1 frame pose for each, as long the file have something to play when the game calls. 
Click here to see Vanilla Animation Names list.
= Textures =
For the head to be able to have different textures (you do not need to have separate textures if you do not want) the folder patch needs to be character/skins/human_male or human_female. I tried to use a folder named 'horse_male' but the engine cannot find the face texture then. It only works if you use the vanilla folder names for humanoid races.
Body and head masks determine which parts of the body can be colorized using the editor limits xml.
= Troubleshooting =
Q: Why is my toter's behind curving down? 
A: You have one of the main animation strips not done aka the new bones at the aft are not included in the main strips that is played currently. Also you may have keyframes for those bones in any of the co-animations, where they should not be. Or you have slightly different rotation of one bone in any of the co-animations. Co-animations are 'ref08', 'postures', 'none', 'stand1', 'breathing nonarms', 'neckset, 'shoulder set' and the two turnheads. Make sure every main animation strip has data for each bone, and every co-animation strip only data for the vanilla bones (the game knows how to turn these off on the main strip) and any expressive bone, such as tail and ears (no data on main file for the expressive bones). Also check the strip influence. The combination of strips playing together should result to 1. If you have two strips with influence of one playing at the same time you get issues. Remember to set the blending to 'combine'.
Q: None of my animations are playing, the character hovers above ground unmoving.
A: Make sure all the animation strip names are clean and do not have a .001 or a extra space at the end. Also, did you remember to make an animations file in FCS and assign the file to the race of the character? Did you export the mesh one animation strip clicked on (star is white)? Did you by accident select some other mesh with the skeleton, that is not parented to it?
Q: An animation keeps on playing even tho the character has stopped walking (or which ever animation it was).
A: Your animation strip has the wrong frames per second setting. Fe. the game plays walking anim at 25 frames/sec. If you have set your walk anim fe. 20 frames/sec the animation continues to play until all frames have been played. And as the game plays the stand pose at the end of walking, it has only 2 frames, so the frames 30 to 35 of the walk anim keep on playing beyond the stand pose. Always use the same frame rate as vanilla animations, 24 frames/sec. At least make sure both walk upper and walk lower have the same framerate,
Sometimes Kenshi also plays as default the animation strip topmost of the list, so make sure you have a one-frame animation at the top.
Q: My animal walks and runs funnily
A: Check all of the animations playing together (neckset, shoulder set etc,) and make sure the back legs do not have keyframes on the co-animations. In the same vain, make sure walk, jog and running animations have only the front legs (human lower) saved on lower file and the back legs only on upper file. The game knows how to play bones named with vanilla Bip01 etc. but they cannot automatically tone in the new back legs. Remember, the front legs are the lower legs of a human, back legs are new.
Q: Suddenly one of the body parts of the animal is huge compared to other body parts
A: This may be one (or more) of the animation strips affecting that body part is corrupted. You have to redo those strips I am afraid.
= Glossary =
 	
Assigning Animations	The act of opening the race file and adding the animation reference to it using the drop down menu.
Assistant Bone 	A bone you created just to aid you making bone link chains. Delete after use.
Co-Animations 	My umbrella name for all the animations that Kenshi plays with the main animation. These are: Breathing, Breathing noarms, Neckset, Shoulder set, Postures, Ref08 and turnhead and idle_turnhead. 'none' is not a co-animation, it is a pose reset.
Expressive bones 	All bones that are included to provide fluff, such as tails and ears. Maybe wings. Wings are tough, you need to include their movement to every pose, cannot put them to co-animations or you would not get the result you want.
Photobooth bones 	My petname for the three bones, that prevent the game crashing when a NPC is talking to the toter. The bones are Bip01 Neck, Bip01 Head and Bip01 HeadNub, set in a humanoid figuration in correct height. If you used the human as base and grow more bones to it, these are already in correct place.
Toter   	A combination word for a rideable animal or vehicle, much less cumbersome to write.
           
                                      
Category:Animation
Category:Modding
Category:Custom race
Category:Custom character
Category:Wip