Skip to content

Developer Usage

Jump to bottom
Tslat edited this page Oct 24, 2024 · 27 revisions

TES provides a pretty accessible and flexible API for developers to use to integrate their own HUD elements or particle implementations. It also gives easy access to the config options, held entity states, and other runtime data TES uses.

This opens the mod up for plenty of inter-compatibility options in an easy-to-use manner.

Setup

First we'll need to add in the maven repo and dependency to the build.gradle file

Repository

Forge/NeoForge 
repositories {
	maven {
		name = "TslatEntityStatus (TES) Maven Repo"
		url = "https://dl.cloudsmith.io/public/tslat/tes/maven/"
	}
}
Fabric 
repositories {
	maven {
		name = "TslatEntityStatus (TES) Maven Repo"
		url = "https://dl.cloudsmith.io/public/tslat/tes/maven/"
	}

	// Need to include Modrinth API for MidnightLib
	forRepository {
		maven {
			name = "Modrinth"
			url = "https://api.modrinth.com/maven"
		}
	}
}

Dependency

Then add in the dependency to your dependencies block:

NeoForge 
dependencies {
	implementation fg.deobf("net.tslat.tes:TES-neoforge-${project.minecraft_version}:${project.tes_version}")
	// Example: implementation fg.deobf("net.tslat.tes:TES-neoforge-1.21.1:1.6.4")
}
Forge 
dependencies {
	implementation fg.deobf("net.tslat.tes:TES-forge-${project.minecraft_version}:${project.tes_version}")
	// Example: implementation fg.deobf("net.tslat.tes:TES-forge-1.21.1:1.6.4")
}

Forge Mixin Support

TES uses mixins to run, and if you're on Forge you will need to include mixin support for it to run in your IDE

// Include the mixin plugin in your plugins block at the top of your build.gradle
plugins {
	id 'org.spongepowered.mixin' version '0.7.+'
}

// Then add the refmap properties to your run configurations
runs {
	client {
		// Other existing lines here
		property 'mixin.env.remapRefMap', 'true'
		property 'mixin.env.refMapRemappingFile', "${buildDir}/createSrgToMcp/output.srg"
	}

	server {
		// Other existing lines here
		property 'mixin.env.remapRefMap', 'true'
		property 'mixin.env.refMapRemappingFile', "${buildDir}/createSrgToMcp/output.srg"
	}
}

// Then add the annotations processor to your dependencies
dependencies {
	// Other dependencies here

    if (System.getProperty("idea.sync.active") != "true") {
        annotationProcessor 'org.spongepowered:mixin:0.8.5:processor'
    }
}
Fabric 
dependencies {
	modImplementation "net.tslat.tes:TES-fabric-${project.minecraft_version}:${project.tes_version}"
	// Example: modImplementation "net.tslat.tes:TES-fabric-1.21.1:1.6.4"
	modLocalRuntime "maven.modrinth:midnightlib:1.6.3-fabric"
	// Need to add MidnightLib because fabric doesn't do transitive deps on included jars
}

Mixin Plugin markers

You'll need to add plugin marker support to your settings.gradle file so that MixinGradle can function properly:

pluginManagement {
    resolutionStrategy {
        eachPlugin {
            if (requested.id.toString() == 'org.spongepowered.mixin') {
                useModule("org.spongepowered:mixingradle:${requested.version}")
            }
        }
    }
}

Then refresh your gradle project and regen your run configurations, and you're good to go!

Usage

Almost all of the files useful to you as a mod developer will be found in the api package.

Of particular note are the following classes, which are most likely to contain the things you're looking for:

Adding a TES Particle

TES makes particle access easy! Simply make a new instance of TESParticle or one of its existing subclasses, then pass it to TESAPI#addTESParticle The rest will be taken care of for you.

Rendering, positioning, validity, and everything else is handled inside the TESParticle instance While TES's particles are client-side only, the mod does allow you to add particles from the server-side. This is handled automatically for you if you use the API method mentioned above.

Adding a TES HUD Element

TES has two 'HUD' components; the on-screen HUD, and the in-world HUD. Both of these components are handled simultaneously in the same instance of TESHudElement

To add your own HUD element, create a new instance of TESHudElement and pass it to TESAPI#addTESHudElement at mod-initialization time along with its ID, and the rest will be handled for you. Elements added to the HUD will be dependably-ordered, with each sequential being pre-positioned relative to the last element automatically before your render method is called

Handling damage particles for specific damage types (DamageSources)

TES has a built-in system that allows for third-party mods to handle TESParticles specially, depending on the DamageSource of the latest attack. This allows for a mod to make special particles or other effects when an entity is damaged, predicated by the DamageSource of that attack, such as a special particle for fire damage, etc.

To do this, you register your TESParticleSourceHandler via TESAPI#registerParticleSourceHandler on the client side. This should be done at mod startup.

From there, TES will check your handler for every damage event that occurs, and will defer to you when you want to handle the event.

Handling particles for specific events (Submitting a claim)

TES has a built-in system that allows for third-party mods to 'claim' some or all of the damage of an attack from either the server or client-side, allowing that mod to then generate its own particle in its place. In short, what this means is that you can do custom particles for custom damage types, or just special particles of your own making at damage time, instead of the default TES particle.

To do this, you submit a 'claim' for some amount of damage, as the damage is being done. This requires two steps:

  1. You register a 'claimant' on the client-side. This is essentially your handler that handles your claims. Your claimant is called when a claim is made, and you can add new custom particles to the adder provided. You then return the amount of damage remaining after your claim, which allows for TES or other mods to handle the remaining amount as needed
  2. You submit a 'claim'. This is done through TESAPI#submitParticleClaim. You send through the ID of the claimant you want to handle the claim, and optionally any additional data (such as the intended amount of damage to claim), and your claimant will receive that at the time of the claim.
Clone this wiki locally