Vital Signals

[ English | 简体中文 ]

A library that provides detailed player status information and an event system for Minecraft mods. This library offers a Mod-friendly API, enabling other mods to receive and process events regarding important player status changes such as health, hunger, oxygen levels, and more.

Introduction

Vital Signals is an event library designed specifically for Minecraft mod developers. It leverages the Fabric API to provide low-level event hooks and network synchronization, allowing mods to precisely track various player attribute changes.

• 🎯 Detailed Data Capture: Captures every stage of the damage calculation process.
• 🔧 Mod-friendly API: Simple and easy-to-use event registration system.
• 📡 Automatic Network Synchronization: Server automatically syncs data to clients.
• 🛡️ Complete Damage Reduction Information: Records all sources of damage reduction (armor, shield, magic, etc.).

Features

Completed Features

Damage Event ✅

A comprehensive damage calculation tracking system that records all detailed information when a player takes damage.

Planned Features

• 🔜 Death Event [v0.2.0]: Complete information upon player death.
• 🔜 Hunger Event [v0.3.0]: Changes in hunger and saturation levels.
• 🔜 Oxygen Event [v0.4.0]: Changes in underwater oxygen levels.

Quick Start

Adding Dependency

Add this library to your build.gradle:

repositories {
    mavenCentral()
    maven { url 'https://jitpack.io' }
}

dependencies {
    modImplementation 'com.github.Rainy-day-y:Vital-Signals:v0.1.2'
}

Damage Event Data Structure (DamageData)

Data structure sent over the network for damage events, using NBT format:

Field	Type	Description
gameVersion	String	Minecraft game version
version	Int	Data format version number
isDirect	Boolean	Whether it is direct damage
typeId	Int	Damage type ID
phase	String	Current damage calculation phase
isCancelled	Boolean	Whether the damage is cancelled
damageAmount	Float	Final damage value (actual impact on health)
rawDamageAmount	Float	Raw damage value
difficultyReduced	Float	Difficulty reduction amount
shieldBlocked	Float	Shield block amount
iceReduced	Float	Frost Walker boot reduction
helmetReduced	Float	Turtle Shell / Snow Boots reduction
armorReduced	Float	Armor reduction amount
effectAndEnchantmentReduced	Float	Magic effects and enchantment reduction
absorbed	Float	Damage absorption amount
otherReduced	Float	Other reductions (calculated difference)

Data Packet Example

{
  gameVersion: "1.21.1",
  version: 1,
  isDirect: true,
  typeId: 0,
  phase: "FINAL",
  isCancelled: false,
  damageAmount: 5.0,
  rawDamageAmount: 10.0,
  difficultyReduced: 0.0,
  shieldBlocked: 0.0,
  iceReduced: 0.0,
  helmetReduced: 0.0,
  armorReduced: 2.0,
  effectAndEnchantmentReduced: 0.5,
  absorbed: 2.5,
  otherReduced: 0.0
}

Roadmap

v0.1.2 (Current Version) - Damage Event

• Damage event infrastructure
• Complete damage reduction information capture
• Network synchronization to client
• Mod-friendly API

v0.2.0 (Planned) - Death Event

• Player death event trigger
• Detailed death cause information
• Pre-item drop hooks
• Experience point drop information

v0.3.0 (Planned) - Hunger Event

• Hunger level change event
• Saturation level change event
• Hunger status change

v0.4.0 (Planned) - Oxygen Event

• Oxygen level change event
• Drowning status tracking
• Water breathing effect detection

v1.0.0 (Planned) - Full Release

• All core events refined
• API stability guarantee
• Complete documentation and examples
• Performance optimization

License

This project is licensed under the MIT License.

Contributing

Issues and Pull Requests are welcome! For suggestions or questions, please contact us via GitHub Issues.

Related Links

• Fabric API Documentation
• Minecraft Wiki