Make characters (player avatars) moddable

[ohlidalp]

Needs updated rorserver: https://github.com/RigsOfRods/ror-server/pull/153

Present rorbot is 100% hardcoded which prevents artists like Vido from really improving him. And while at it, it makes sense to make him 100% moddable.

The classic rorbot is now a mod as well, and lives in /resources/default_character.zip. If no other mod is installed, game falls back to this one.

I've created a detailed tutorial for complete beginners: https://forum.rigsofrods.org/threads/beginner-tutorial-character-rorbot-mod-from-scratch-in-blender.3761/ - it will guide you through modelling, animating and exporting with Blender and blender2ogre.

Example character mod (from the above tutorial): rorbotmod-tut1-rev1.zip

To use it, just place it anywhere in your mods directory and enable it using Settings UI/Gameplay tab.

[ohlidalp]

Regarding rorbot, I have these thoughts:

• we want to fade animations in and out, like when running and stopping. This involves the Blend Weight param but possibly playback speed.
• we need something like soundscripts for animations, they allow defining start/stop effects.
• While at it, I might as well make rorbot a new type of mod, with a definition file, recognized by modcache and selectable with selector. Not much work, I did it all before, see my 'addon_API' branch in my repo.
• Since we now have a navigation mesh system with built in ability to guide crowds of of point figures like rorbot, this all nicely fits together
• see also MakeHuman project.

And that was only the part on visuals! Further on the simulation like movement:

• historically it was simply "set pos, rot, animation type and time of the entity" directly from main loop where pos/rot was updated.
• then I added simbuffers, but animations are still decided on simulation side, visual side just updates the entity.
• for Vido I hacked a secondary animation channel to the simbuffer, but otherwise no change.
• what we need is to do things properly like with actors:
  1. On sim side, only pos/ rot is calculated and written to simbuffer, with some hint what action is being done like idle, running etc...
  2. On visuals side, the logic from above post is applied.

TL;DR: Present rorbot is 100% hardcoded which prevents artists like Vido from really improving him. And while at it, it makes sense to make him 100% moddable.

[ohlidalp]

This (very satisfying!) new debug UI shows the animation definitions and visualizes if, and why, they're running.

Red flags block the animation. Green flags let the animation run. Yellow flags let the animation run, but some are missing or the animation is blocked. Dark blue flags mean nothing blocks the animation.

[ohlidalp]

Added (even more satisfying) inline display mode to 'Game anims' UI.

[ohlidalp]

I added support for bone blend masks, see https://ogrecave.github.io/ogre/api/1.11/class_ogre_1_1_animation_state.html#a06594a53335afbe8ccb67331e35a32fd

Example for the stock character.mesh (disables all upper body animation when running, see above GIF):

begin_bone_blend_mask
    anim_name "Run"
    bone_weight "hand.R" 0
    bone_weight "hand.L" 0
    bone_weight "forearm.R" 0
    bone_weight "forearm.L" 0
    bone_weight "upper_arm.R" 0
    bone_weight "upper_arm.L" 0
    bone_weight "shoulder.R" 0
    bone_weight "shoulder.L" 0
    bone_weight "head" 0
    bone_weight "neck" 0
    bone_weight "chest" 0
    bone_weight "spine" 0
end_bone_blend_mask

[ohlidalp]

Purpose: to make the rorbot 100% moddable

Estimate: 2 man days. The hard part is done, the character-def fileformat is proven to work by Vido using dev-build.

Work to be done: ModCache needs to be updated to recognize rorbot mods. I've done this before, see https://github.com/only-a-ptr/rigs-of-rods/commit/bf95ca930c3ad51d9d5c1759f4eefa8d05020280

[ohlidalp]

I've added modcache support for character mods, and a RoR.cfg option to specify the default character, which you can also configure from Settings UI via selector. Soon I'll move the classic RORbot from resources directory to content directory.

[CuriousMike56]

Unfortunately I've been unable to load into any terrains with this. Upon downloading and extracting the Windows build from GitHub, attempting to load a terrain gave me this:

01:09:52: [RoR|General|Error] Could not find character 'classic.character' in mod cache.

First thought was that maybe classic.character wasn't included by default, so I checked resources\skeleton.zip and strangely enough, realized that every file in that zip is duplicated: This is also the case for all the other dev builds I've downloaded. They're definitely exact copies as attempting to extract them gives me an overwrite prompt. All other resource zips appear to be unaffected.

Continuing on, I went to move classic.character to My Games\Rigs of Rods\config which turns out that file was already created on launch. In RoR, the classic.character file appears in settings but the character selector is empty: I searched mods.cache and didn't find any mention of the character file. There should definitely be an emergency fallback if no character files are found.

Then I tried your rorbotmod-tut1-rev1.zip file, placed that file into the mods folder and launched the game. The character selector now shows the mod: Attempting to load any terrain now fails with this error in the log:

01:18:39:  ===== TERRAIN LOADING DONE 2af11UID-f1_testtrack.terrn2
01:18:39: [RoR|CVar]      sim_terrain_name:  "2af11UID-f1_testtrack.terrn2" (was: "")
01:18:39: [RoR|CVar]  sim_terrain_gui_name:  "f1_testtrack 0.8" (was: "")
01:18:39: Ogre::ItemIdentityException::ItemIdentityException: Cannot locate a resource group called '' for resource 'rorbotmod-tut1-rev1.character' in ResourceGroupManager::openResource at C:\Users\runneradmin\.conan\data\ogre3d\1.11.6.1\anotherfoxguy\stable\build\f7f69c899d0ea5d1d2b62305f3102aa1a22dede5\OgreMain\src\OgreResourceGroupManager.cpp (line 675)
01:18:39: [RoR|General|Error] Could not load character, message: Ogre::ItemIdentityException::ItemIdentityException: Cannot locate a resource group called '' for resource 'rorbotmod-tut1-rev1.character' in ResourceGroupManager::openResource at C:\Users\runneradmin\.conan\data\ogre3d\1.11.6.1\anotherfoxguy\stable\build\f7f69c899d0ea5d1d2b62305f3102aa1a22dede5\OgreMain\src\OgreResourceGroupManager.cpp (line 675)

I also tried copying classic.character to the mods folder, which makes it show up in the selector but still throws the above error.

Another (possibly unrelated) error I had when testing this build was when I tried to load another terrain after receiving the "failed to create character" error: Disabling particle gfx doesn't solve this. I'm reporting this here as I can't reproduce it with other builds.

[ohlidalp]

@CuriousMike56 Thanks for the exhaustive testing and sorry about the confusion with the default rorbot. The game now loads rorbots exclusively from the mods directory, so the config/classic.character won't be found anymore - I need to delete it. Also the classic rorbot needs to be uploaded to the content repo (alongside agora bus and DAF semitruck).

[CuriousMike56]

Adding the classic RoRBot zip to mods allows terrains to load now, but the character is giant and with no texture (same result as Tritonas on Discord). Loading your character mod crashes the game when loading the skeleton:

09:20:19: Creating resources for group bundle C:\Users\Mike\Documents\My Games\Rigs of Rods\mods\rorbotmod-tut1-rev1.zip
09:20:19: All done
09:20:19: Mesh: Loading rorbotmod-tut1.mesh.
09:20:19: Skeleton: Loading rorbotmod-tut1.skeleton

This brings me to the biggest problem I have with this PR, there's no fallback to the current hardcoded character. If that's not possible, then at the very least the default RoRBot absolutely should be kept in the resources directory and not treated as a mod. There's quite a few players out there who don't read the docs and assume mods are installed in the content folder. These are the same players that end up removing the other default content. If you find yourself on a populated multiplayer server try spawning one of the default vehicles, you'd be surprised to see that there's a good chance at least one person on that server doesn't have the vehicle installed.

With the current setup there's bound to be people who delete the character zip from the content directory thinking it's not required then come to #game-support wondering why they can't load any terrains.

[ohlidalp]

@CuriousMike56 Thanks for testing, sorry about the giant size glitch (I forgot to add mesh_scale to the definition file). My idea is to migrate the default rorbot from "resources" directories to the "content" directory, as ZIP, alongside Agora and DAF Semi. If anyone messes with files in there it's their fight, I'd just add "reinstall the game" note in the "can't load terrain - no character" dialog and be done with that. My priority is keeping the codebase straightforward (=less bug prone), which means using rorbot mods exclusively.

EDIT: OK, I see that it's either me taking the hit of maintaining more code (the alternate codepath of loading rorbot from the resources), or you getting the hit of more idiots spamming #support. The problem is, the old rorbot code is gone - the game uses the .character definitions exclusively, and I did that to enable Vido to just extend the default rorbot without hassle. Hardcoding the defs would take that away.

[ohlidalp]

@CuriousMike56 I think I figured out a setup which will satisfy everyone:

• rorbot mods will live in /mods, be enlisted in modcache and selected using Selector UI in the Settings.
• the default rorbot will also be a mod,enlisted in modcache and selected using Selector UI in the Settings. However, it's resources will be in /resources/character.zip. That way, the extra code for me to maintain will be minimal:
  • tell modcache to scan /resources/character* too.
  • If the chosen character mod isn't found, use this one.

[CuriousMike56]

Perfect, as long the default character lives in the resources directory I'm good with that 👍 So far the only odd thing I've noticed with the default character animations is that now the character T-poses when pressing the A/D keys and left/right arrow keys at the same time. This might be just due to Vido's updated animations not being completed yet (assuming they're a part of this PR?)

Current (latest master) behavior:

https://user-images.githubusercontent.com/46073351/201974658-023d38a5-9c37-4098-8c21-4bc0e781b881.mp4

Now:

https://user-images.githubusercontent.com/46073351/201977713-61736249-a5c2-4564-8ca5-26dacdbc5e03.mp4

It appears that its not playing any animation in both clips, just that latest master is defaulting to the idle pose instead of T-posing.

[tritonas00]

Button now is too small, harder to catch. You could make SmallButton a Button again and properly align text with the button:

ImGui::AlignTextToFramePadding();
ImGui::Text();
ImGui::SameLine();
ImGui::Button();

Also pressing Cancel in the character selector makes main menu visible

What happens in MP with this? Like player A has character A, player B has character B and player A doesn't have character B installed for example. Will he be able to see the default character in this case? Or everyone see the character that they selected in settings?

[ohlidalp]

@tritonas00 Thanks for testing.

• Vido's changes are not part of this PR, it just introduces the modding system and remakes the classic character using it.
• The T-pose is a corner case of the animation def system, kudos for discovering it, I need to figure out how to prevent that.
• I'll fix the Settings as you suggest, both the button and the main menu glitch.
• In multiplayer, the plan is to match rorbots the same way vehicles are matched. If not installed, the default rorbot would be used. The ACTION_ and SITUATION_ flags are already transferred over network, so equivalent animations will be played. However, currently it's not implemented and everyone will appear using the locally configured rorbot. I'm not sure whether I should rush to do this or wait until someone actually wishes for this (which means some decent rorbot mods already exist).

[CuriousMike56]

I tried to convert the 0.38 character I uploaded to the Repository (https://forum.rigsofrods.org/resources/classic-characters.959/) into a mod, the game crashes when trying to load the skeleton:

00:20:45: Finished parsing scripts for resource group bundle C:\Users\Mike\Documents\My Games\Rigs of Rods\mods\038_character.zip
00:20:45: Creating resources for group bundle C:\Users\Mike\Documents\My Games\Rigs of Rods\mods\038_character.zip
00:20:45: All done
00:20:45: Mesh: Loading 038-character.mesh.
00:20:45: Skeleton: Loading 038-character.skeleton
00:20:45: Texture '038-character.dds': Loading 1 faces(PF_DXT1,512x512x1) with 9 custom mipmaps from Image. Internal format is PF_DXT1,512x512x1.
00:20:45: Texture '038-character-alpha.png': Loading 1 faces(PF_A8R8G8B8,512x512x1) Internal format is PF_A8R8G8B8,512x512x1.

I also tried taking the classic character (the file should be renamed to "default_character.zip` IMO) and renamed all the files to prevent conflicts, it too crashes the game with the same last line in the log.

038_character.zip classic-character-vest.zip

[ohlidalp]

@CuriousMike56 RoRbot mods can't cause conflicts, each loads to separate resource group like other mods, and the default rorbot is also a mod. But I'll rename it to default_character.zip, no problem.

The crash with default rorbot hapenned before or after the renaming?

[CuriousMike56]

RoRbot mods can't cause conflicts, each loads to separate resource group like other mods, and the default rorbot is also a mod. But I'll rename it to default_character.zip, no problem.

The crash with default rorbot hapenned before or after the renaming?

After, every character mod that isn't the default one (including yours) crashes.

RoRBot mods conflict the same way vehicles can, if both .character files are named the same. classic_character-vest-not-renamed.zip This is supposed to have the safety vest skin from https://forum.rigsofrods.org/resources/rorbot-safety-vest-skin.328/ , selecting it just results in the default character being loaded instead (confirmed by the fact it doesn't crash) By looking at RoR.log, this makes sense:

00:59:43: [RoR|CVar]  sim_player_character:  "classic.character" (was: "classic-vest.character")

The game doesn't know which zip to load classic.character from, so it just loads the first one in the cache.

[ohlidalp]

@CuriousMike56 RoRBot mods conflict the same way vehicles can, if both .character files are named the same.

You're right, I had different "conflict" in mind (OGRE resource names). Yes, this happens because the selector UI requests loading mods by filename (except skins which use CacheEntry* directly).

[ohlidalp]

I dusted this off and renamed things to resolve ambiguity with "animation" meaning either skeletal animation or game-defined animation. Ambiguity is bad.

Changes:

• game animations (defined in the .character file) ale now called Actions. the begin/end_animation is now begin/end_action.
• ACTION_ flags were renamed to CONTROL_ flags.

Recap of how the system works:

• A skeletal animation is a named animation track in OGRE '*.skeleton' file, like "Walk", "Swim", "Side_step"...
• User defines 'actions' via .character file, by specifying a skeletal anim name to play and game state flags which trigger/block it.
• SITUATION_ flags tell you what circumstances the character is in (on ground, in deep water, driving...)
• CONTROL_ flags tell you what controller input is the player giving (go forward, turn, sidestep...)

difference between custom action vs mode?

• CONTROL_CUSTOM_ACTION = press-and-hold playback. Release key: playback stops. Same thing as like run/walk/sidestep.
• SITUATION_CUSTOM_MODE = press-to-toggle mode. It's like SITUATION_DRIVING when you enter a vehicle, but with toggle key.

Preliminary documentation of ".character" file format:

• The 'default.character' file has introductory comments on top: https://github.com/only-a-ptr/rigs-of-rods/blob/vido-rorbot-anims/resources/default_character/default.character
• begin/end_action values are described here: https://github.com/only-a-ptr/rigs-of-rods/blob/vido-rorbot-anims/source/main/resources/character_fileformat/CharacterFileFormat.h#L48-L73
• The global values are described here: https://github.com/only-a-ptr/rigs-of-rods/blob/vido-rorbot-anims/source/main/resources/character_fileformat/CharacterFileFormat.h#L90-L101

[CuriousMike56]

Works nicely now 👍 Only issue I've noticed is changing the character after returning to menu requires a restart.

[ohlidalp]

Known defects

• mp crash https://discord.com/channels/136544456244461568/189904947649708032/1120112468669239346
• multiple skins https://discord.com/channels/136544456244461568/189904947649708032/1120396644341522533

Feature suggestions

• origin offset https://discord.com/channels/136544456244461568/189904947649708032/1120072821478010942