Particles - Revision history

ChampionAsh5357: Update to 1.17

2021-08-02T21:26:10Z

Update to 1.17

ShrimpBot: Categorize with Category:Game Effects by SizableShrimp#0755

2021-05-18T23:15:07Z

Categorize with Category:Game Effects by SizableShrimp#0755

SciWhiz12: Text replacement - "{{Colored box|title=Important|content=" to "{{Tip/Important|"

2020-12-20T18:11:06Z

Text replacement - "{{Colored box|title=Important|content=" to "{{Tip/Important|"

Unbekannt: Inital Import dokuwiki

2020-10-25T11:37:19Z

Inital Import dokuwiki

New page

Particles are one of the few effects within the game that are used as polish to better improve immersion. Their usefulness also requires great caution due to how they are created and referenced in the game.

== Sided Issues ==
Particles are problematic due to their presence only on the [[Sides|physical client]]. They have no existence on a server whatsoever. This means that if specific data from a server is needed, it needs to be synced from the server to create the particle on the client.

== Creating a Particle ==
A particle can be broken up into four distinct classes. On the server, a <code>ParticleType<?></code> holds an <code>IParticleData</code> to sync the information. On the client, an <code>IParticleFactory</code> is used to generate a <code>Particle</code> from the synced <code>IParticleData</code>. To be more specific, a <code>ParticleType<?></code> holds the registry reference of the particle itself. An <code>IParticleData</code> hooks into a <code>ParticleType<?></code> to send information to the <code>IParticleFactory</code>. An <code>IParticleFactory</code> creates the specified particle in some place within the world. Then, the <code>Particle</code> goes and handles the rendering logic to make it appear in game.

=== <code>ParticleType</code>s ===

While there are a lot of different particles in vanilla, in almost all cases vanilla uses <code>BasicParticleType</code>, a basic implementation of <code>ParticleType</code> and <code>IParticleData</code>. This is used whenever server data is not necessary to spawn the particle. The only vanilla particles that do not use <code>BasicParticleType</code> are redstone dust and block/item texture dependent particles. When requiring server data, a direct implementation of <code>IParticleData</code> is needed. A good way is to extend <code>ParticleType<?></code> and implement <code>IParticleData</code> on the same class. In the case of a more generic solution, an implementation of <code>IParticleData</code> can be referenced while the standard <code>ParticleType<?></code> class is used.

<code>ParticleType</code>s must be [[Registration#registering-things|registered]].

=== <code>IParticleData</code> ===

Beside the standard reference to a <code>ParticleType<?></code>, an <code>IParticleData</code> is made up of two main methods and two accessory methods for compatibility across Minecraft usage.

First there are the sync methods:
<syntaxhighlight lang="java">
IParticleData#write(PacketBuffer)

IParticleData$IDeserializer#read(ParticleType, PacketBuffer)
</syntaxhighlight>

These two are used to sync information across the network. All information from the server should be synced in this fashion.

The other two are for compatibility with other Minecraft systems:
<syntaxhighlight lang="java">
IParticleData#getParameters

IParticleData$IDeserializer#deserialize(ParticleType, StringReader)
</syntaxhighlight>

These two are used to read/write data to NBT as well as get information to spawn the particle in the world using a command.

=== <code>Particle</code>s ===

<code>Particle</code>s will be left as an exercise to the reader as it is mainly about deciding what the reader wants to render to the screen. One of the most common classes to subclass, however, is <code>SpriteTexturedParticle</code>. This abstract class renders a texture specified by the user as the particle to go according to the logic rendered.

=== <code>IParticleFactory</code>s ===
Finally, a particle must be created using an <code>IParticleFactory</code>. This simply just decides where the particle should be placed in the world at some speed in most cases. Since a <code>Particle</code> is not beholden to any particular <code>ParticleType<?></code>, it can be reused over and over again in different factories if necessary.

An <code>IParticleFactory</code> must be attached to a <code>ParticleType</code> using <code>ParticleManager#registerFactory</code>. This should be called during <code>ParticleFactoryRegisterEvent</code> on the mod event bus.

{{Colored box|title=Important|content=<code>IParticleFactory</code> is only present on the client, so the event needs to be isolated via <code>DistExecutor</code> or some other method.}}

== Spawning Particles ==
Particles can be spawned from a world instance. Each side, however, has a specific way of calling them. The <code>ClientWorld</code> can call either <code>addParticle</code> or <code>addOptionalParticle</code>. The <code>ServerWorld</code> must call <code>spawnParticle</code> as it sends a packet to the client world to call one of the other two methods. Calling the two <code>ClientWorld</code> methods on the server will result in nothing happening.

← Older revision		Revision as of 23:15, 18 May 2021
Line 49:		Line 49:
	== Spawning Particles ==		== Spawning Particles ==
	Particles can be spawned from a world instance. Each side, however, has a specific way of calling them. The <code>ClientWorld</code> can call either <code>addParticle</code> or <code>addOptionalParticle</code>. The <code>ServerWorld</code> must call <code>spawnParticle</code> as it sends a packet to the client world to call one of the other two methods. Calling the two <code>ClientWorld</code> methods on the server will result in nothing happening.		Particles can be spawned from a world instance. Each side, however, has a specific way of calling them. The <code>ClientWorld</code> can call either <code>addParticle</code> or <code>addOptionalParticle</code>. The <code>ServerWorld</code> must call <code>spawnParticle</code> as it sends a packet to the client world to call one of the other two methods. Calling the two <code>ClientWorld</code> methods on the server will result in nothing happening.
		+
		+
		+	[[Category:Game Effects]]

@@ Line 5: / Line 5: @@
 == Creating a Particle ==
-A particle can be broken up into four distinct classes. On the server, a <code>ParticleType<?></code> holds an <code>IParticleData</code> to sync the information. On the client, an <code>IParticleFactory</code> is used to generate a <code>Particle</code> from the synced <code>IParticleData</code>. To be more specific, a <code>ParticleType<?></code> holds the registry reference of the particle itself. An <code>IParticleData</code> hooks into a <code>ParticleType<?></code> to send information to the <code>IParticleFactory</code>. An <code>IParticleFactory</code> creates the specified particle in some place within the world. Then, the <code>Particle</code> goes and handles the rendering logic to make it appear in game.
+A particle can be broken up into four distinct classes. On the server, a <code>ParticleType<?></code> holds a <code>ParticleOptions</code> to sync the information. On the client, a <code>ParticleProvider</code> is used to generate a <code>Particle</code> from the synced <code>ParticleOptions</code>. To be more specific, a <code>ParticleType<?></code> holds the registry reference of the particle itself. A <code>ParticleOptions</code> hooks into a <code>ParticleType<?></code> to send information to the <code>ParticleProvider</code>. A <code>ParticleProvider</code> creates the specified particle in some place within the level. Then, the <code>Particle</code> goes and handles the rendering logic to make it appear in game.
 === <code>ParticleType</code>s ===
-While there are a lot of different particles in vanilla, in almost all cases vanilla uses <code>BasicParticleType</code>, a basic implementation of <code>ParticleType</code> and <code>IParticleData</code>. This is used whenever server data is not necessary to spawn the particle. The only vanilla particles that do not use <code>BasicParticleType</code> are redstone dust and block/item texture dependent particles. When requiring server data, a direct implementation of <code>IParticleData</code> is needed. A good way is to extend <code>ParticleType<?></code> and implement <code>IParticleData</code> on the same class. In the case of a more generic solution, an implementation of <code>IParticleData</code> can be referenced while the standard <code>ParticleType<?></code> class is used.
+While there are a lot of different particles in vanilla, in almost all cases vanilla uses <code>SimpleParticleType</code>, a basic implementation of <code>ParticleType</code> and <code>ParticleOptions</code>. This is used whenever server data is not necessary to spawn the particle. The only vanilla particles that do not use <code>SimpleParticleType</code> are redstone dust and block/item texture dependent particles. When requiring server data, a direct implementation of <code>ParticleOptions</code> is needed. A good way is to extend <code>ParticleType<?></code> and implement <code>ParticleOptions</code> on the same class. In the case of a more generic solution, an implementation of <code>ParticleOptions</code> can be referenced while the standard <code>ParticleType<?></code> class is used.
 <code>ParticleType</code>s must be [[Registration#registering-things|registered]].
-=== <code>IParticleData</code> ===
+=== <code>ParticleOptions</code> ===
-Beside the standard reference to a <code>ParticleType<?></code>, an <code>IParticleData</code> is made up of two main methods and two accessory methods for compatibility across Minecraft usage.
+Beside the standard reference to a <code>ParticleType<?></code>, a <code>ParticleOptions</code> is made up of two main methods and two accessory methods for compatibility across Minecraft usage.
 First there are the sync methods:
 <syntaxhighlight lang="java">
-IParticleData#write(PacketBuffer)
+ParticleOptions#writeToNetwork(FriendlyByteBuf)
-IParticleData$IDeserializer#read(ParticleType, PacketBuffer)
+ParticleOptions$Deserializer#fromNetwork(ParticleType, FriendlyByteBuf)
 </syntaxhighlight>
@@ Line 28: / Line 28: @@
 The other two are for compatibility with other Minecraft systems:
 <syntaxhighlight lang="java">
-IParticleData#getParameters
+ParticleOptions#writeToString
-IParticleData$IDeserializer#deserialize(ParticleType, StringReader)
+ParticleOptions$Deserializer#fromCommand(ParticleType, StringReader)
 </syntaxhighlight>
-These two are used to read/write data to NBT as well as get information to spawn the particle in the world using a command.
+These two are used to read/write data to NBT as well as get information to spawn the particle in the level using a command.
 === <code>Particle</code>s ===
-<code>Particle</code>s will be left as an exercise to the reader as it is mainly about deciding what the reader wants to render to the screen. One of the most common classes to subclass, however, is <code>SpriteTexturedParticle</code>. This abstract class renders a texture specified by the user as the particle to go according to the logic rendered.
+<code>Particle</code>s will be left as an exercise to the reader as it is mainly about deciding what the reader wants to render to the screen. One of the most common classes to subclass, however, is <code>TextureSheetParticle</code>. This abstract class renders a texture specified by the user as the particle to go according to the logic rendered.
-=== <code>IParticleFactory</code>s ===
+=== <code>ParticleProvider</code>s ===
-Finally, a particle must be created using an <code>IParticleFactory</code>. This simply just decides where the particle should be placed in the world at some speed in most cases. Since a <code>Particle</code> is not beholden to any particular <code>ParticleType<?></code>, it can be reused over and over again in different factories if necessary.
+Finally, a particle must be created using a <code>ParticleProvider</code>. This simply just decides where the particle should be placed in the level at some speed in most cases. Since a <code>Particle</code> is not beholden to any particular <code>ParticleType<?></code>, it can be reused over and over again in different factories if necessary.
-An <code>IParticleFactory</code> must be attached to a <code>ParticleType</code> using <code>ParticleManager#registerFactory</code>. This should be called during <code>ParticleFactoryRegisterEvent</code> on the mod event bus.
+A <code>ParticleProvider</code> must be attached to a <code>ParticleType</code> using <code>ParticleEngine#register</code>. If a particle has a json defined sprite location, then the <code>ParticleEngine$SpriteParticleRegistration</code> variant must be used instead as otherwise an exception will be thrown. This should be called during <code>ParticleFactoryRegisterEvent</code> on the mod event bus.
-{{Tip/Important|<code>IParticleFactory</code> is only present on the client, so the event needs to be isolated via <code>DistExecutor</code> or some other method.}}
+{{Tip/Important|<code>ParticleProvider</code> is only present on the client, so the event needs to be isolated via <code>DistExecutor</code> or some other method.}}
 == Spawning Particles ==
-Particles can be spawned from a world instance. Each side, however, has a specific way of calling them. The <code>ClientWorld</code> can call either <code>addParticle</code> or <code>addOptionalParticle</code>. The <code>ServerWorld</code> must call <code>spawnParticle</code> as it sends a packet to the client world to call one of the other two methods. Calling the two <code>ClientWorld</code> methods on the server will result in nothing happening.
+Particles can be spawned from a level instance. Each side, however, has a specific way of calling them. The <code>ClientLevel</code> can call either <code>addParticle</code> or <code>addAlwaysVisibleParticle</code>. The <code>ServerLevel</code> must call <code>sendParticles</code> as it sends a packet to the client level to call one of the other two methods. Calling the two <code>ClientLevel</code> methods on the server will result in nothing happening.
 [[Category:Game Effects]]