Skip to content

Commit 362280b

Browse files
IchHabeHunger54IchHabeHunger54
committed
use mermaid diagrams
1 parent 6652351 commit 362280b

File tree

3 files changed

+191
-33
lines changed

3 files changed

+191
-33
lines changed

‎docs/entities/index.md

Lines changed: 89 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -295,27 +295,106 @@ EntityType.Builder.of(...)
295295

296296
Due to the many different types of entities, there is a complex hierarchy of subclasses of `Entity`. These are important to know about when choosing what class to extend when making your own entity, as you will be able to save a lot of work by reusing their code.
297297

298-
Direct subclasses of `Entity` include:
298+
The vanilla entity hierarchy looks like this (red classes are `abstract`, blue classes are not):
299+
300+
```mermaid
301+
graph LR;
302+
Entity-->Projectile;
303+
Entity-->LivingEntity;
304+
Entity-->BlockAttachedEntity;
305+
BlockAttachedEntity-->LeashFenceKnotEntity;
306+
BlockAttachedEntity-->HangingEntity;
307+
HangingEntity-->ItemFrame;
308+
ItemFrame-->GlowItemFrame;
309+
HangingEntity-->Painting;
310+
Entity-->PartEntity;
311+
PartEntity-->EnderDragonPart;
312+
Entity-->VehicleEntity;
313+
VehicleEntity-->AbstractBoat;
314+
AbstractBoat-->AbstractChestBoat;
315+
AbstractChestBoat-->ChestBoat;
316+
AbstractChestBoat-->ChestRaft;
317+
AbstractBoat-->Boat;
318+
AbstractBoat-->Raft;
319+
VehicleEntity-->AbstractMinecart;
320+
AbstractMinecart-->AbstractMinecartContainer;
321+
AbstractMinecartContainer-->MinecartChest;
322+
AbstractMinecartContainer-->MinecartHopper;
323+
AbstractMinecart-->Minecart;
324+
AbstractMinecart-->MinecartCommandBlock;
325+
AbstractMinecart-->MinecartFurnace;
326+
AbstractMinecart-->MinecartSpawner;
327+
AbstractMinecart-->MinecartTNT;
328+
329+
class Entity,Projectile,LivingEntity,BlockAttachedEntity,HangingEntity,PartEntity,VehicleEntity,AbstractBoat,AbstractChestBoat,AbstractMinecart,AbstractMinecartContainer red;
330+
class LeashFenceKnotEntity,ItemFrame,GlowItemFrame,Painting,EnderDragonPart,ChestBoat,ChestRaft,Boat,Raft,MinecartChest,MinecartHopper,Minecart,MinecartCommandBlock,MinecartCommandBlock,MinecartFurnace,MinecartSpawner,MinecartTNT blue;
331+
```
332+
333+
Let's break these down:
299334

300335
- `Projectile`: The base class for various projectiles, including arrows, fireballs, snowballs, fireworks and similar entities. Read more about them [below][projectile].
301336
- `LivingEntity`: The base class for anything "living", in the sense of it having things like hit points, equipment, [mob effects][mobeffect] and some other properties. Includes things such as monsters, animals, villagers, and players. Read more about them in the [Living Entities article][livingentity].
302-
- `VehicleEntity`: The base class for boats and minecarts. While these entities loosely share the concept of hit points with `LivingEntity`s, they do not share many other properties with them and are as such kept separated.
303-
- `BlockAttachedEntity`: The base class for entities that are immobile and attached to blocks. Includes leash knots, item frames and paintings.
304-
- `Display`: The base class for the various map-maker display entities.
337+
- `BlockAttachedEntity`: The base class for entities that are immobile and attached to blocks. Includes leash knots, item frames and paintings. The subclasses mainly serve the purpose of reusing common code.
338+
- `PartEntity`: The base class for part entities, i.e. entities made up of multiple smaller entities. Vanilla currently only uses this for the Ender Dragon.
339+
- `VehicleEntity`: The base class for boats and minecarts. While these entities loosely share the concept of hit points with `LivingEntity`s, they do not share many other properties with them and are as such kept separated. The subclasses mainly serve the purpose of reusing common code.
340+
341+
There are also several entities that are direct subclasses of `Entity`, simply because there was no other fitting superclass. Most of these should be self-explanatory:
305342

306-
Several entities are also direct subclasses of `Entity`, simply because there was no other fitting superclass. Prominent examples include `ItemEntity` (dropped items), `LightningBolt`, `ExperienceOrb` and `PrimedTnt`.
343+
- `AreaEffectCloud` (lingering potion clouds)
344+
- `EndCrystal`
345+
- `EvokerFangs`
346+
- `ExperienceOrb`
347+
- `EyeOfEnder`
348+
- `FallingBlockEntity` (falling sand, gravel etc.)
349+
- `ItemEntity` (dropped items)
350+
- `LightningBolt`
351+
- `OminousItemSpawner` (for continuously spawning the loot of trial spawners)
352+
- `PrimedTnt`
353+
354+
Not included in this diagram and list are the mapmaker entities (displays, interactions and markers).
307355

308356
### Projectiles
309357

310358
Projectiles are a subgroup of entities. Common to them is that they fly in one direction until they hit something, and that they have an owner assigned to them (e.g. a player or a skeleton would be the owner of an arrow, or a ghast would be the owner of a fireball).
311359

312-
There are three big subgroups of projectiles:
360+
The class hierarchy of projectiles looks as follows (red classes are `abstract`, blue classes are not):
361+
362+
```mermaid
363+
graph LR;
364+
Projectile-->AbstractArrow;
365+
AbstractArrow-->Arrow;
366+
AbstractArrow-->SpectralArrow;
367+
AbstractArrow-->ThrownTrident;
368+
Projectile-->AbstractHurtingProjectile;
369+
AbstractHurtingProjectile-->AbstractWindCharge;
370+
AbstractWindCharge-->BreezeWindCharge;
371+
AbstractWindCharge-->WindCharge;
372+
AbstractHurtingProjectile-->DragonFireball;
373+
AbstractHurtingProjectile-->Fireball;
374+
Fireball-->LargeFireball;
375+
Fireball-->SmallFireball;
376+
AbstractHurtingProjectile-->WitherSkull;
377+
Projectile-->FireworkRocketEntity;
378+
Projectile-->FishingHook;
379+
Projectile-->LlamaSpit;
380+
Projectile-->ShulkerBullet;
381+
Projectile-->ThrowableProjectile;
382+
ThrowableProjectile-->ThrowableItemProjectile;
383+
ThrowableItemProjectile-->Snowball;
384+
ThrowableItemProjectile-->ThrownEgg;
385+
ThrowableItemProjectile-->ThrownEnderpearl;
386+
ThrowableItemProjectile-->ThrownExperienceBottle;
387+
ThrowableItemProjectile-->ThrownPotion;
388+
389+
class Projectile,AbstractArrow,AbstractHurtingProjectile,AbstractWindCharge,Fireball,ThrowableProjectile,ThrowableItemProjectile red;
390+
class Arrow,SpectralArrow,ThrownTrident,BreezeWindCharge,WindCharge,DragonFireball,LargeFireball,SmallFireball,WitherSkull,FireworkRocketEntity,FishingHook,LlamaSpit,ShulkerBullet,Snowball,ThrownEgg,ThrownEnderpearl,ThrownExperienceBottle,ThrownPotion blue;
391+
```
313392

314-
- Arrows: Represented by the `AbstractArrow` superclass, this group covers the different kinds of arrows, as well as the trident. An important common property is that they will not fly straight, but are affected by gravity.
315-
- Throwables: Represented by the `ThrowableProjectile` superclass, this group covers things like eggs, snowballs and ender pearls. Like arrows, they are affected by gravity, but unlike arrows, they will not inflict damage upon hitting the target. They are also all spawned by using the corresponding item.
316-
- Hurting Projectiles: Represented by the `AbstractHurtingProjectile` superclass, this group covers wind charges, fireballs and wither skulls. These are damaging projectiles unaffected by gravity.
393+
Of note are the three direct abstract subclasses of `Projectile`:
317394

318-
Other projectiles that directly extend `Projectile` include fireworks, fishing bobbers and shulker bullets.
395+
- `AbstractArrow`: This class covers the different kinds of arrows, as well as the trident. An important common property is that they will not fly straight, but are affected by gravity.
396+
- `AbstractHurtingProjectile`: This class covers wind charges, various fireballs, and wither skulls. These are damaging projectiles unaffected by gravity.
397+
- `ThrowableProjectile`: This class covers things like eggs, snowballs and ender pearls. Like arrows, they are affected by gravity, but unlike arrows, they will not inflict damage upon hitting the target. They are also all spawned by using the corresponding [item].
319398

320399
A new projectile can be created by extending `Projectile` or a fitting subclass, and then overriding the methods required for adding your functionality. Common methods to override include:
321400

‎docs/entities/livingentity.md

Lines changed: 75 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -104,33 +104,94 @@ _See [Containers on Entities][containers]._
104104

105105
## Hierarchy
106106

107-
Living entities have a complex class hierarchy. As mentioned before, the three direct subclasses are `ArmorStand`, `Mob` and `Player`. Of these, `ArmorStand` has no subclasses, so we will focus on the class hierarchy of `Mob` and `Player`.
107+
Living entities have a complex class hierarchy. As mentioned before, there are three direct subclasses:
108+
109+
```mermaid
110+
graph LR;
111+
LivingEntity-->ArmorStand;
112+
LivingEntity-->Mob;
113+
LivingEntity-->Player;
114+
```
115+
116+
Of these, `ArmorStand` has no subclasses (and is also the only non-abstract class), so we will focus on the class hierarchy of `Mob` and `Player`.
108117

109118
### Hierarchy of `Mob`
110119

111-
`Mob`'s most important subclass is `PathfinderMob`, which contains (surprise!) logic for pathfinding. `PathfinderMob`'s subclasses are as follows:
120+
The class hierarchy of `Mob` looks as follows (red classes are `abstract`, blue classes are not):
121+
122+
```mermaid
123+
graph LR;
124+
Mob-->AmbientCreature;
125+
AmbientCreature-->Bat;
126+
Mob-->EnderDragon;
127+
Mob-->FlyingMob;
128+
FlyingMob-->Ghast;
129+
FlyingMob-->Phantom;
130+
Mob-->PathfinderMob;
131+
PathfinderMob-->AbstractGolem;
132+
AbstractGolem-->IronGolem;
133+
AbstractGolem-->Shulker;
134+
AbstractGolem-->SnowGolem;
135+
PathfinderMob-->AgeableMob;
136+
AgeableMob-->AbstractVillager;
137+
AbstractVillager-->Villager;
138+
AbstractVillager-->WanderingTrader;
139+
AgeableMob-->AgeableWaterCreature;
140+
AgeableWaterCreature-->Dolphin;
141+
AgeableWaterCreature-->Squid;
142+
Squid-->GlowSquid;
143+
AgeableMob-->Animal;
144+
PathfinderMob-->Allay;
145+
PathfinderMob-->Monster;
146+
PathfinderMob-->WaterAnimal;
147+
WaterAnimal-->AbstractFish;
148+
AbstractFish-->AbstractSchoolingFish;
149+
AbstractSchoolingFish-->Cod;
150+
AbstractSchoolingFish-->Salmon;
151+
AbstractSchoolingFish-->TropicalFish;
152+
AbstractFish-->Pufferfish;
153+
AbstractFish-->Tadpole;
154+
Mob-->Slime;
155+
Slime-->MagmaCube;
156+
157+
class Mob,AmbientCreature,FlyingMob,PathfinderMob,AbstractGolem,AgeableMob,AbstractVillager,AgeableWaterCreature,Animal,Monster,WaterAnimal,AbstractFish,AbstractSchoolingFish red;
158+
class Bat,EnderDragon,Ghast,Phantom,IronGolem,Shulker,SnowGolem,Villager,WanderingTrader,Dolphin,Squid,GlowSquid,Allay,Cod,Salmon,TropicalFish,Pufferfish,Tadpole,Slime,MagmaCube blue;
159+
```
160+
161+
All other living entities missing from the diagram are subclasses of either `Animal` or `Monster`.
112162

113-
- `AbstractGolem`: The superclass for iron golems, snow golems and (for some reason) shulkers.
114-
- `AgeableMob`: This class has two direct subclasses `AbstractVillager` and `Animal`, both of which should be self-explanatory. These contain most of the aging logic. `Animal` additionally has the abstract `TamableAnimal` subclass that is used for tamable animals such as wolves, cats and parrots; as well as the `AbstractHorse` subclass, which is the superclass of horses, donkeys and mules.
115-
- `Allay`: Allays directly extend `PathfinderMob`.
116-
- `Monster`: The abstract class for everything the game considers monsters. Like `Animal`, this has various abstract subclasses, such as `AbstractPiglin`, `AbstractSkeleton`, `Raider`, and `Zombie`.
117-
- `WaterAnimal`: The superclass for water-based animals, such as fish, squids and dolphins. These are kept separate from the other animals due to significantly different pathfinding.
163+
As you may have noticed, this is very messy. For example, why aren't bees, parrots etc. also flying mobs? This problem becomes even worse when looking into the subclass hierarchy of `Animal` and `Monster`, which will not be discussed here in detail (look them up using your IDE's Show Hierarchy feature if you're interested). It is best to acknowledge it, but not worry about it.
118164

119-
Some other classes also extend `Mob` directly. These include `AmbientCreature` with its only subclass `Bat`, `EnderDragon`, `FlyingMob` with its two subclasses `Ghast` and `Phantom` (no, there is no consistency here whatsoever), and `Slime` and its `MagmaCube` subclass.
165+
Let's go over the most important classes:
166+
167+
- `PathfinderMob`: Contains (surprise!) logic for pathfinding.
168+
- `AgeableMob`: Contains the logic for aging and baby entities. Zombies and other monsters with baby variants do not extend this class, they instead are children of `Monster`.
169+
- `Animal`: What most animals extend. Has further abstract subclasses, such as `AbstractHorse` or `TamableAnimal`.
170+
- `Monster`: The abstract class for most entities the game considers monsters. Like `Animal`, this has further abstract subclasses, such as `AbstractPiglin`, `AbstractSkeleton`, `Raider`, and `Zombie`.
171+
- `WaterAnimal`: The abstract class for water-based animals, such as fish, squids and dolphins. These are kept separate from the other animals due to significantly different pathfinding.
120172

121173
### Hierarchy of `Player`
122174

123-
Depending on which side the player is on, a different player class is used:
175+
Depending on which side the player is on, a different player class is used. You should never need to construct a player yourself, except for `FakePlayer`s.
176+
177+
```mermaid
178+
graph LR;
179+
Player-->AbstractClientPlayer;
180+
AbstractClientPlayer-->LocalPlayer;
181+
AbstractClientPlayer-->RemotePlayer;
182+
Player-->ServerPlayer;
183+
ServerPlayer-->FakePlayer;
184+
```
124185

125-
- `ServerPlayer`: This class is used to represent players on the [logical server][logicalsides].
126-
- `FakePlayer`: This is a special subclass of `ServerPlayer` designed to be used as a mock for a player, for non-player mechanisms that need a player context.
127186
- `AbstractClientPlayer`: This class is used as a base for the two client players, both used to represent players on the [logical client][logicalsides].
128-
- `LocalPlayer`: This class is used to represent the player currently running the game.
129-
- `RemotePlayer`: This class is used to represent other players that the `LocalPlayer` may encounter during multiplayer. `RemotePlayer`s do not exist in singleplayer contexts.
187+
- `LocalPlayer`: This class is used to represent the player currently running the game.
188+
- `RemotePlayer`: This class is used to represent other players that the `LocalPlayer` may encounter during multiplayer. As such, `RemotePlayer`s do not exist in singleplayer contexts.
189+
- `ServerPlayer`: This class is used to represent players on the [logical server][logicalsides].
190+
- `FakePlayer`: This is a special subclass of `ServerPlayer` designed to be used as a mock for a player, for non-player mechanisms that need a player context.
130191

131192
## Spawning
132193

133-
In addition to the [regular ways of spawning][spawning], `Mob`s can also be spawned through some other means. `ArmorStand`s can be spawned through regular means, and `Player`s should not be instantiated yourself.
194+
In addition to the [regular ways of spawning][spawning], `Mob`s can also be spawned through some other means. `ArmorStand`s can be spawned through regular means, and `Player`s should not be instantiated yourself, except for `FakePlayer`s.
134195

135196
### Spawn Eggs
136197

‎docs/entities/renderer.md

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -66,20 +66,38 @@ That's literally it. Extend the class, add your field, and off you go. The only
6666
6767
## Hierarchy
6868
69-
Like with entities themselves, entity renderers also have a class hierarchy, though not as layered. It basically boils down to:
69+
Like entities themselves, entity renderers have a class hierarchy, though not as layered. The most important classes of the hierarchy are related like this (red classes are `abstract`, blue classes are not):
70+
71+
```mermaid
72+
graph LR;
73+
EntityRenderer-->AbstractBoatRenderer;
74+
EntityRenderer-->AbstractMinecartRenderer;
75+
EntityRenderer-->ArrowRenderer;
76+
EntityRenderer-->LivingEntityRenderer;
77+
LivingEntityRenderer-->ArmorStandRenderer;
78+
LivingEntityRenderer-->MobRenderer;
79+
MobRenderer-->AgeableRenderer;
80+
AgeableRenderer-->HumanoidMobRenderer;
81+
LivingEntityRenderer-->PlayerRenderer;
82+
83+
class EntityRenderer,AbstractBoatRenderer,AbstractMinecartRenderer,ArrowRenderer,LivingEntityRenderer,MobRenderer,AgeableRenderer,HumanoidMobRenderer red;
84+
class ArmorStandRenderer,PlayerRenderer blue;
85+
```
7086
71-
- `EntityRenderer`: The abstract base class. Many entities, notably almost all non-living ones, extend this class directly.
72-
- `ArrowRenderer`, `AbstractBoatRenderer`, `AbstractMinecartRenderer`: These exist mainly for convenience, and are used as parents for more specific renderers. `ArrowRenderer` is also used directly by the regular arrow entity.
73-
- `LivingRenderer`: The abstract base class for renderers for [living entities][livingentity]. Direct subclasses include `ArmorStandRenderer` and `PlayerRenderer`.
74-
- `MobRenderer`: The abstract base class for renderers for `Mob`s. Many renderers extend this directly.
75-
- `AgeableRenderer`: The abstract base class for renderers for `Mob`s that have child variants. This includes monsters with child variants, such as hoglins.
76-
- `HumanoidMobRenderer`: The abstract base class for humanoid entity renderers. Used by e.g. zombies and skeletons.
87+
- `EntityRenderer`: The abstract base class. Many renderers, notably almost all renderers for non-living entities, extend this class directly.
88+
- `ArrowRenderer`, `AbstractBoatRenderer`, `AbstractMinecartRenderer`: These exist mainly for convenience, and are used as parents for more specific renderers.
89+
- `LivingEntityRenderer`: The abstract base class for renderers for [living entities][livingentity]. Direct subclasses include `ArmorStandRenderer` and `PlayerRenderer`.
90+
- `ArmorStandRenderer`: Self-explanatory.
91+
- `PlayerRenderer`: Used to render players. Note that unlike most other renderers, multiple instances of this class used for different contexts may exist at the same time.
92+
- `MobRenderer`: The abstract base class for renderers for `Mob`s. Many renderers extend this directly.
93+
- `AgeableRenderer`: The abstract base class for renderers for `Mob`s that have child variants. This includes monsters with child variants, such as hoglins.
94+
- `HumanoidMobRenderer`: The abstract base class for humanoid entity renderers. Used by e.g. zombies and skeletons.
7795
78-
As with the various entity classes, use what fits your use case most. Be aware that many of these classes have corresponding type bounds in their generics; for example, `LivingRenderer` has type bounds for `LivingEntity` and `LivingEntityRenderState`.
96+
As with the various entity classes, use what fits your use case most. Be aware that many of these classes have corresponding type bounds in their generics; for example, `LivingEntityRenderer` has type bounds for `LivingEntity` and `LivingEntityRenderState`.
7997
8098
## Entity Models and Layer Definitions
8199
82-
Many renderers, especially the `LivingRenderer` and its subclasses, make use of `EntityModel`s. `EntityModel`s are basically a list of cubes and associated textures for the renderer to use. They are commonly created statically when the entity renderer's constructor is first created.
100+
Many renderers, especially the `LivingEntityRenderer` and its subclasses, make use of `EntityModel`s. `EntityModel`s are basically a list of cubes and associated textures for the renderer to use. They are commonly created statically when the entity renderer's constructor is first created.
83101

84102
Entity models use a layer system, where each layer is represented as a `LayerDefinition`. A renderer can use multiple layers, and the renderer can decide what layer(s) to render at what time. For example, the elytra uses a separate layer that is rendered independently of the `LivingEntity` wearing it. Similarly, player capes are also a separate layer.
85103

0 commit comments

Comments
 (0)