Make characters (player avatars) moddable

resources/materials/character.material → resources/default_character/character.material

@@ -1,6 +1,6 @@
 import * from "managed_mats.material"
 
-material tracks/character: RoR/Managed_Mats/Base
+material character: RoR/Managed_Mats/Base
 {
 	technique BaseTechnique
 	{
@@ -12,19 +12,21 @@ material tracks/character: RoR/Managed_Mats/Base
 				texture character.dds
 			}
 		}
+
+        // The multiplayer colorization pass - must be named "ColorChange"
 		pass ColorChange
 		{
 			scene_blend alpha_blend
+            // The alpha mask texture unit - name doesn't matter.
 			texture_unit
 			{
 				texture character-alpha.png
 			}
-			texture_unit
+            // The color texture unit - must be named "PlayerColor"
+			texture_unit "PlayerColor"
 			{
 				colour_op_ex blend_current_alpha src_manual src_current 0 0 0
 			}
 		}
 	}
-}
-
-
+}

resources/default_character/default.character

@@ -0,0 +1,200 @@
+; The default character (aka RoRbot)
+; -----------------------------------------------------------------------------
+;
+; This file format lets you compose 'actions' from one or more
+;  skeletal animations exported from a 3D modelling tool,
+;  by responding to SITUATION_ and CONTROL_ flags sent by the game.
+;  NOTE each 'action' is evaluated separately, there is no either-or relation,
+;  so you must always blacklist all non-conforming flags to avoid conflicts.
+;
+; For explanation of individual parameters,
+;  see file source/main/resources/character_fileformat/CharacterFileFormat.h
+;  NOTE ON TERMINOLOGY: 'anim' always means skeletal animation, not the 'action'.
+;
+; For authoritative list of SITUATION_ and CONTROL_ flags, see file RoRnet.h
+;
+; Tip: in game, use 'Pose Util' UI panel,
+;  open it from top menubar >> Tools >> Character pose util.
+;
+; -----------------------------------------------------------------------------
+
+; Name displayed in the Selector UI - required
+character_name "Default character"
+
+; required for skinning - use https://guidgenerator.com for your mods.
+character_guid "baef1af5-2854-48c3-af05-5087da2d773b"
+
+; Name of the mesh file - required.
+mesh_name "character.mesh"
+
+; Scaling factor of the mesh - optional, default is 1.0 on all axes.
+; NOTE: the 0.02 factor used to be hardcoded because the default character mesh is oversized like that.
+mesh_scale 0.02 0.02 0.02
+
+begin_action
+    action_description "driving"
+    for_situation SITUATION_DRIVING
+    anim_name "Driving"
+    playback_time_ratio 0.f
+    playback_steering_ratio -1.f
+    anim_continuous false
+    source_percentual true
+    anim_neutral_mid true
+    playback_trim 0.01f  
+end_action
+
+begin_action
+    action_description "swimming"
+    for_situation SITUATION_IN_DEEP_WATER
+    for_control CONTROL_MOVE_FORWARD
+    anim_name "Swim_loop"
+    playback_h_speed_ratio 1.f
+    playback_time_ratio 1.f
+end_action
+
+begin_action
+    action_description "swimming on spot"
+    for_situation SITUATION_IN_DEEP_WATER
+    except_control CONTROL_MOVE_FORWARD
+    anim_name "Spot_swim"
+    playback_time_ratio 1.f
+end_action
+
+begin_action
+    action_description "running"
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING
+    for_control CONTROL_MOVE_FORWARD
+    for_control CONTROL_RUN
+    anim_name "Run"
+    playback_time_ratio 1.f
+    playback_h_speed_ratio 1.f
+end_action
+
+begin_action
+    action_description "walking forward"
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING
+    for_control CONTROL_MOVE_FORWARD
+    except_control CONTROL_RUN
+    ; when pressing both FORWARD+BACKWARD keys, FORWARD wins in game movement so let it win here also.
+    except_control CONTROL_MOVE_BACKWARD
+    anim_name "Walk"
+    playback_time_ratio 1.f
+    playback_h_speed_ratio 1.f
+end_action
+
+begin_action
+    action_description "walking backward"
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING
+    for_control CONTROL_MOVE_BACKWARD
+    ; Do not mix the walk animation into the run animation if user presses both RUN+MOVE_BACKWARDS.
+    except_control CONTROL_RUN
+    anim_name "Walk"
+    playback_time_ratio -1.f
+    playback_h_speed_ratio 1.f
+end_action
+
+begin_action
+    action_description "side stepping right"
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING
+    for_control CONTROL_SIDESTEP_RIGHT
+    except_control CONTROL_MOVE_FORWARD
+    except_control CONTROL_MOVE_BACKWARD
+    ; Pressing both SIDESTEP+TURN controls makes game combine the movements, so also combine the animations.
+    ;except_control CONTROL_TURN_RIGHT
+    ;except_control CONTROL_TURN_LEFT
+    except_control CONTROL_RUN
+    anim_name "Side_step"
+    playback_time_ratio 1.f
+    anim_autorestart true
+end_action
+
+begin_action
+    action_description "side stepping left"
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING
+    for_control CONTROL_SIDESTEP_LEFT
+    except_control CONTROL_MOVE_FORWARD
+    except_control CONTROL_MOVE_BACKWARD
+    ; Pressing both SIDESTEP+TURN controls makes game combine the movements, so also combine the animations.
+    ;except_control CONTROL_TURN_RIGHT
+    ;except_control CONTROL_TURN_LEFT
+    except_control CONTROL_RUN
+    anim_name "Side_step"
+    playback_time_ratio -1.f
+    anim_autorestart true
+end_action
+
+begin_action
+    action_description "turning left"
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING
+    for_control CONTROL_TURN_LEFT
+    ; Pressing both SIDESTEP+TURN controls makes game combine the movements, so also combine the animations.
+    ;except_control CONTROL_SIDESTEP_LEFT
+    ;except_control CONTROL_SIDESTEP_RIGHT
+    except_control CONTROL_MOVE_FORWARD
+    except_control CONTROL_MOVE_BACKWARD
+    except_control CONTROL_RUN
+    anim_name "Turn"
+    playback_time_ratio 1.f
+    anim_autorestart true
+end_action
+
+begin_action
+    action_description "turning right"
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING
+    for_control CONTROL_TURN_RIGHT
+    ; Pressing both SIDESTEP+TURN controls makes game combine the movements, so also combine the animations.
+    ;except_control CONTROL_SIDESTEP_LEFT
+    ;except_control CONTROL_SIDESTEP_RIGHT
+    except_control CONTROL_MOVE_FORWARD
+    except_control CONTROL_MOVE_BACKWARD
+    except_control CONTROL_RUN
+    anim_name "Turn"
+    playback_time_ratio -1.f
+    anim_autorestart true
+end_action
+
+begin_action
+    action_description "idle standing"
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING
+    except_situation SITUATION_CUSTOM_MODE_01
+    except_control CONTROL_TURN_RIGHT
+    except_control CONTROL_TURN_LEFT
+    except_control CONTROL_SIDESTEP_LEFT
+    except_control CONTROL_SIDESTEP_RIGHT
+    except_control CONTROL_MOVE_FORWARD
+    except_control CONTROL_MOVE_BACKWARD
+    except_control CONTROL_RUN
+    except_control CONTROL_CUSTOM_01
+    anim_name "Idle_sway"
+    playback_time_ratio 1.f
+end_action
+
+begin_action
+    action_description "custom action 01 test"
+    for_control CONTROL_CUSTOM_ACTION_01
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING    
+    except_situation SITUATION_CUSTOM_MODE_01
+    anim_name "Spot_swim"
+    playback_time_ratio 10.0
+    anim_continuous false
+end_action
+
+begin_action
+    action_description "custom mode 01 test"
+    for_situation SITUATION_CUSTOM_MODE_01
+    except_situation SITUATION_IN_DEEP_WATER
+    except_situation SITUATION_DRIVING    
+    anim_name "Driving"
+    playback_time_ratio 2.0    
+end_action
+
+

source/main/Application.cpp

@@ -108,6 +108,8 @@ CVar* sim_no_self_collisions;
 CVar* sim_gearbox_mode;
 CVar* sim_soft_reset_mode;
 CVar* sim_quickload_dialog;
+CVar* sim_player_character;
+CVar* sim_player_character_skin;
 
 // Multiplayer
 CVar* mp_state;
@@ -122,6 +124,8 @@ CVar* mp_server_password;
 CVar* mp_player_name;
 CVar* mp_player_token;
 CVar* mp_api_url;
+CVar* mp_override_character;
+CVar* mp_override_character_skin;
 
 // New remote API
 CVar* remote_query_url;

source/main/Application.h

@@ -39,7 +39,7 @@
 
 #define ROR_ASSERT(_EXPR)  assert(_EXPR)
 
-#define CHARACTER_ANIM_NAME_LEN 10 // Restricted for networking
+#define DEFAULT_CHARACTER_FILE "default.character" // Located in file 'resources/default_character.zip'
 
 // Legacy macros
 #define TOSTRING(x)     Ogre::StringConverter::toString(x)
@@ -251,6 +251,8 @@ enum VisibilityMasks
 enum LoaderType //!< Operation mode for GUI::MainSelector
 {
     LT_None,
+    LT_Character, // No script alias, invoked from Settings UI.
+    LT_CharacterMP,// No script alias, invoked from Multiplayer Lobby UI.
     LT_Terrain,   // Invocable from GUI; No script alias, used in main menu
     LT_Vehicle,   // Script "vehicle",   ext: truck car
     LT_Truck,     // Script "truck",     ext: truck car
@@ -303,6 +305,8 @@ extern CVar* sim_no_self_collisions;
 extern CVar* sim_gearbox_mode;
 extern CVar* sim_soft_reset_mode;
 extern CVar* sim_quickload_dialog;
+extern CVar* sim_player_character;
+extern CVar* sim_player_character_skin;
 
 // Multiplayer
 extern CVar* mp_state;
@@ -317,6 +321,8 @@ extern CVar* mp_server_password;
 extern CVar* mp_player_name;
 extern CVar* mp_player_token;
 extern CVar* mp_api_url;
+extern CVar* mp_override_character; // If empty, use `sim_default_character`
+extern CVar* mp_override_character_skin;
 
 // New remote API
 extern CVar* remote_query_url;

source/main/CMakeLists.txt

@@ -33,6 +33,7 @@ set(SOURCE_FILES
         gfx/DustPool.{h,cpp}
         gfx/EnvironmentMap.{h,cpp}
         gfx/GfxActor.{h,cpp}
+        gfx/GfxCharacter.{h,cpp}
         gfx/GfxData.h
         gfx/GfxScene.{h,cpp}
         gfx/HydraxWater.{h,cpp}
@@ -114,6 +115,7 @@ set(SOURCE_FILES
         gui/imgui/imstb_textedit.h
         gui/imgui/imstb_truetype.h
         gui/panels/GUI_AngelScriptExamples.{h,cpp}
+        gui/panels/GUI_CharacterPoseUtil.{h,cpp}
         gui/panels/GUI_CollisionsDebug.{h,cpp}
         gui/panels/GUI_ConsoleView.{h,cpp}
         gui/panels/GUI_ConsoleWindow.{h,cpp}
@@ -191,6 +193,7 @@ set(SOURCE_FILES
         resources/skin_fileformat/SkinFileFormat.{h,cpp}
         resources/terrn2_fileformat/Terrn2FileFormat.{h,cpp}
         resources/tobj_fileformat/TObjFileFormat.{h,cpp}
+        resources/character_fileformat/CharacterFileFormat.{h,cpp}
         system/AppCommandLine.cpp
         system/AppConfig.cpp
         system/Console.{h,cpp}
@@ -341,6 +344,7 @@ target_include_directories(${BINNAME} PRIVATE
         physics/utils
         physics/water
         resources
+        resources/character_fileformat
         resources/odef_fileformat/
         resources/otc_fileformat/
         resources/rig_def_fileformat

source/main/ForwardDeclarations.h

@@ -37,6 +37,9 @@ namespace RoR
     typedef int ScriptUnitId_t; //!< Unique sequentially generated ID of a loaded and running scriptin session. Use `ScriptEngine::getScriptUnit()`
     static const ScriptUnitId_t SCRIPTUNITID_INVALID = -1;
 
+    typedef int CharacterActionID_t; //!< Index to `CharacterDocument::actions`, use `CHARACTERACTIONID_INVALID` as empty value.
+    static const CharacterActionID_t CHARACTERACTIONID_INVALID = -1;
+
     typedef int PointidID_t; //!< index to `PointColDetector::hit_pointid_list`, use `RoR::POINTIDID_INVALID` as empty value.
     static const PointidID_t POINTIDID_INVALID = -1;