Modular Char

A Godot plugin for building 2D characters from separate body parts. Parts are placed through visual Marker2D sockets, equipped with data-driven weapons, and animated entirely in code, so a single rig can be reskinned and re-equipped at runtime without touching the scene.

✨ Features

• Part-based: Character assembled from body, head, mouth, legs, cape, shield and weapon
• Visual sockets: Placement driven by Marker2D nodes instead of hardcoded positions
• Data-driven weapons: ModularCharWeapon resource with per-type idle pose and attack curve
• Code-driven animations: Blending, looping, queueing and a ready-made default set
• Built-in shadow: Adjustable visibility, opacity and distance
• Runtime swapping: Change skins, weapons, shield and cape on the fly
• Signals: animation_started, animation_finished, animation_looped, attack_finished, facing_changed
• 2D only: Production-grade, no deprecated APIs

📦 Installation

1. Copy the addons/modular_char folder into your Godot project.
2. Enable the plugin in Project → Project Settings → Plugins.
3. ModularChar is registered as a custom Node2D type you can add from the scene dock.

🚀 Basic Usage

# instance the character and register the default animation set
var character: ModularChar = preload("res://addons/modular_char/scenes/modular_char.tscn").instantiate()
add_child(character)
ModularCharDefaultAnimations.register_defaults(character)
character.play_animation("idle")

# assign a body part
var head: ModularCharBodyPart = ModularCharBodyPart.new()
head.scene = load("res://demo/assets/character_2/head.tscn")
head.scale = Vector2(0.48, 0.48)
character.set_head(head)

# equip a weapon
var weapon: ModularCharWeapon = ModularCharWeapon.new()
weapon.scene = load("res://demo/assets/weapons/sword.tscn")
weapon.animation_type = ModularCharWeapon.AnimationType.SWORD
character.set_weapon(weapon)

# act
character.set_facing(1.0)
character.attack()

📖 API Reference

🦴 Body parts

Method	Description
set_body(part: ModularCharBodyPart)	Set the body part.
set_head(part) / set_mouth(part)	Set the head and mouth parts.
set_leg_front(part) / set_leg_back(part)	Set the front and back leg parts.
set_cape(part) / clear_cape()	Set or remove the cape.
set_shield(part) / clear_shield()	Set or remove the shield.
set_shadow(part)	Set the shadow part.

⚔️ Equipment and combat

Method	Description
set_weapon(weapon: ModularCharWeapon) / clear_weapon()	Equip or remove the weapon.
attack() -> void / is_attacking() -> bool	Trigger and query the weapon attack.
set_blocking(enabled: bool) / is_blocking() -> bool	Enter or leave the block pose.
set_weapon_aim_override(enabled: bool, angle_rad: float)	Aim the weapon at a fixed angle.
get_weapon_tip_position() -> Vector2	Global position of the weapon tip.

🎞️ Animation

Method	Description
register_animation(name, animation: ModularCharAnimation)	Register an animation by name.
play_animation(name, duration, transition_time)	Play an animation with optional blend.
queue_animation(name, duration, transition_time)	Queue an animation after the current one.
stop_animation()	Stop the current animation.
get_current_animation() -> String	Name of the playing animation.
get_animation_progress() -> float	Normalized progress in [0, 1].

🧭 Orientation and shadow

Method	Description
set_facing(sign_value: float) / get_facing() -> float	Flip the rig left or right.
set_shadow_visible(value: bool)	Show or hide the shadow.
set_shadow_opacity(opacity: float)	Set the shadow opacity.
set_shadow_distance(percent: float)	Set the shadow size as a percent of its base.

🗡️ Weapons

Weapons are ModularCharWeapon resources holding a scene, an offset and an animation_type. Each type drives its own idle pose and attack curve, so swapping a weapon swaps the whole motion.

Type	Use
SWORD	Overhead melee slash
SPEAR	Forward thrust
THROW	Throwing motion
CROSSBOW	Crossbow shot
GUN	Quick recoil shot
BOW	Draw-and-release shot

🎬 Default Animations

ModularCharDefaultAnimations.register_defaults(character) installs the built-in set: idle, walk, run, jump, hit, block and death.

🎯 Sockets

Open res://addons/modular_char/scenes/modular_char.tscn and tune part placement visually through the markers:

• Rig/BodyAnchor/HeadMarker
• Rig/BodyAnchor/MouthMarker
• Rig/BodyAnchor/CapeMarker
• Rig/BodyAnchor/ShieldMarker
• Rig/BodyAnchor/WeaponMarker
• Rig/LegFrontMarker
• Rig/LegBackMarker
• Rig/ShadowMarker

🎮 Demo

Open demo/scenes/test_world.tscn and run the project.

• Movement: WASD move, Shift run, Space / LMB attack, J jump, Q block
• Panel: Switch skins, swap weapons, toggle shield and cape, toggle aim, fake hit, die, revive and scale the character

💖 Sponsor

If this plugin helps you, consider supporting its development:

• GitHub Sponsors
• Ko-fi

📄 License

This project is licensed under the MIT License.

---

Made with ❤️ by Paulo Coutinho