Entity docs #171

IchHabeHunger54 · 2024-10-03T00:31:19Z

Adds some long-needed entity documentation. Supersedes #15 and #95 . Closes #90 . This PR:

Adds articles about the following:
- Entities in general
- Data and networking in the context of entities
- The LivingEntity, Mob and Player classes, along with their subclasses
- Attributes and AttributeModifiers
- Entity renderers and entity models
Removes the Entities article in the Networking section, in favor of the new Data and Networking article
Updates the Interaction Pipeline article with left-click and middle-click behavior, and also renames it to just Interactions
Adds an explanation for how block breaking speed is calculated, including how the various attributes affect this
- Also does some reformatting in the blocks article, while we're at it
Adds and adjusts links to the new Entities section as necessary
Adds a styleguide for Mermaid class diagrams to the Contributing doc
Explicitly leaves WIP markers for pathfinding, goals and brains, as well as animations, as these deserve their own PR(s)

Preview URL: https://pr-171.neoforged-docs-previews.pages.dev

Co-authored-by: Dennis C <[email protected]>

Co-authored-by: ChampionAsh5357 <[email protected]>

docs/entities/livingentity.md

XFactHD

First pass over the changes, still have to do the 4 largest files.

docs/blocks/index.md

docs/entities/data.md

XFactHD · 2024-12-14T02:46:44Z

docs/entities/renderer.md

+    EntityRenderer-->ArrowRenderer;
+    EntityRenderer-->LivingEntityRenderer;


Suggested change

EntityRenderer-->ArrowRenderer;

EntityRenderer-->LivingEntityRenderer;

EntityRenderer-->LivingEntityRenderer;

EntityRenderer-->ArrowRenderer;

These should be switched around to avoid the arrow from LivingEntityRenderer to ArmorStandRenderer going through the ArrowRenderer node

Changing this makes the arrow go through the AbstractMinecartRenderer instead. I'm afraid there is no easy way of solving this.

XFactHD · 2024-12-14T02:49:49Z

docs/entities/renderer.md

+}
+```
+
+That's literally it. Extend the class, add your field, and off you go. The only thing left to do now is to update that `stackInHand` field in `EntityRenderer#extractRenderState`, as explained above.


This section should include an overview over the render state modification system introduced in neoforged/NeoForge#1650.

XFactHD · 2024-12-14T03:04:36Z

docs/entities/renderer.md

+        if (renderer != null) {
+            // Add the layer to the renderer. Reuses the ModelLayerLocation from above.
+            renderer.addLayer(MY_LAYER);
+        }


This is wrong in two ways:

This event has nothing to do with LayerDefinitions, it's related to RenderLayers. A RenderLayer however can indeed render an EntityModel created from a LayerDefinition after the latter is baked

Only renderers which implement RenderLayerParent can have RenderLayers added to them. In vanilla this only applies to LivingEntityRenderer and its subclasses

RenderLayers should be dealt with in a separate section. This section should instead explain how to go from a LayerDefinition to the custom EntityModel in the renderer's constructor.

XFactHD · 2024-12-14T03:04:51Z

docs/entities/renderer.md

+        // Get the associated PlayerRenderer.
+        if (event.getSkin(skin) instanceof PlayerRenderer playerRenderer) {
+            // Add the layer to the renderer.
+            playerRenderer.addLayer(MY_LAYER);


Same issue as above

docs/entities/data.md

dphaldes · 2024-12-11T01:39:09Z

docs/entities/index.md

+    // Build the entity type. The parameter is a string used for datafixing; mods generally
+    // do not utilize this and can safely pass null here instead.
+    .build(null)


Is this accurate? I copied around this code and it complains about

java.lang.NullPointerException: Cannot invoke "String.indexOf(int)" because "location" is null

Going through neo discord, Commoble says that this string cannot be null. https://discord.com/channels/313125603924639766/983834532904042537/1109539085560856656

This needs to be set as it now attempts to resolve the location of the resource key. A patch needs to be added back in to safely supply null

XFactHD · 2024-12-15T01:28:38Z

docs/entities/data.md

+```
+
+:::danger
+While the compiler will allow you to use a class other than the owning class as the first parameter in `SynchedEntityData#defineId()`, this can and will lead to hard-to-debug issues and as such should be avoided.


I personally prefer the wording used in the old entity networking page. This is not a case of "avoid if possible", it's a case of "seriously, don't do it, it WILL break".
I would also add a note that this includes adding data accessors via mixin to the technically correct class.

ChampionAsh5357

Here's the requested feedback. Still a few WIP sections, so I'm wondering why it was brought out of draft early.

docs/blocks/index.md

ChampionAsh5357 · 2025-01-10T17:17:16Z

docs/concepts/events.md

@@ -120,6 +120,7 @@ graph TD;
    PlayerEvent-->CanPlayerSleepEvent;

    class Event,BlockEvent,EntityEvent,LivingEvent,PlayerEvent red;
+    class BlockDropsEvent,CanPlayerSleepEvent blue;


Is there a reason for this in an entity docs PR?

Mainly because this is the first PR that really makes use of Mermaid diagrams. I adopted the style guide of red -> abstract, blue -> non-abstract, and applied it to the only other diagram we had while I was at it.

docs/entities/attributes.md

docs/entities/livingentity.md

ChampionAsh5357 · 2025-01-10T18:38:56Z

docs/entities/livingentity.md

+Natural spawning is performed every tick for entities where `MobCategory#isFriendly()` is true, and every 400 ticks (\= 20 seconds) for entities where `MobCategory#isFriendly()` is false. If `MobCategory#isPersistent()` returns true, this process additionally also happens on chunk generation.
+
+For each chunk and mob category, it is checked whether there are less than `MobCategory#getMaxInstancesPerChunk() * loadedChunks / 289` in the world. Additionally, for each chunk, it is required that there are less than `MobCategory#getMaxInstancesPerChunk()` entities of that `MobCategory` near at least one player (near means that the distance between mob and player \<\= 128) for spawning of that `MobCategory` to occur.


It might be best to frame this with an example to get the actual numbers for each.

ChampionAsh5357 · 2025-01-10T18:39:08Z

docs/entities/livingentity.md

+:::info
+This section is a work in progress.
+:::
+
+### Brains
+
+:::info
+This section is a work in progress.
+:::
+
+### Navigation
+
+:::info
+This section is a work in progress.
+:::


Work in progress?

Yes, and these sections will not be covered by the PR due to out-of-scope (and also because I do not have the energy to read into these systems at present).

I would just remove the sections for now and stick them in an issue if they're not already.

docs/entities/renderer.md

ChampionAsh5357 · 2025-01-10T18:51:43Z

docs/entities/renderer.md

+}
+```
+
+### Adding a Layer Definition to an Entity


As Xfact mentions, layer definitions are not 'added' to an entity. Instead, the registered ModelLayerLocation is provided to the EntityModelSet to construct the ModelPart used to render the entity model. The below methods are for entity layers such as armor.

neoforged-automation · 2025-01-10T22:33:47Z

@IchHabeHunger54, this pull request has conflicts, please resolve them for this PR to move forward.

# Conflicts: # docs/resources/client/models/bakedmodel.md # docs/resources/server/conditions.md

IchHabeHunger54 and others added 30 commits January 29, 2024 18:04

rework registries and resource location documentation

312442d

rework side documentation

aafbf1b

rework events and lifecycle documentation

a748304

fix broken links

4b2d021

fix some mistakes regarding DeferredRegister.Blocks

c49ff55

add side checks in the event handlers

242abf0

fix some of the mistakes in registries.md

a4971bd

remove mention of registry int id syncing (it is discouraged)

9950d51

Merge remote-tracking branch 'upstream/main'

f64b8fe

update datapack registry datagen

a1bd87d

registry querying

31b5bf2

add back int ID syncing, with a big disclaimer

ff5d5b1

update sync disclaimer

965be16

address most feedback by ChampionAsh

2e65131

Update docs/blocks/index.md

1ed292c

Co-authored-by: Dennis C <[email protected]>

Update docs/concepts/registries.md

e2fbc31

Co-authored-by: Dennis C <[email protected]>

implement most of XFact's feedback

40c17a9

fix datapack registry creation

7a24414

remove recommendation of separate DR and DH classes

55873a1

fix an oversight

cdf58f2

Update docs/blocks/index.md

380db40

Co-authored-by: ChampionAsh5357 <[email protected]>

BootstapContext :screm:

2a369a7

Merge remote-tracking branch 'origin/main'

b1e1966

fix two wrong mentions of Registries

b5a78bb

fix exception name

b6dcbb9

Merge remote-tracking branch 'upstream/main'

8d54466

Merge remote-tracking branch 'upstream/main'

90c3b4a

Merge remote-tracking branch 'refs/remotes/upstream/main'

1d17916

add Champ's previous work on entities

99dd0e6

Merge remote-tracking branch 'origin/main'

a9b38d5

IchHabeHunger54 added 2 commits November 21, 2024 13:44

apply feedback, part 1

2986514

fix wrong name for ArmorHurtEvent

e7ca864

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) November 21, 2024 12:48 Active

IchHabeHunger54 added 4 commits November 26, 2024 13:09

entity renderers, pt 1

79078a2

renderer hierarchy and 1.21.3 update

7b35abe

entity layers, part 1

110be93

entity layers, part 2

56eef02

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) December 1, 2024 21:43 Active

IchHabeHunger54 added 3 commits December 1, 2024 22:47

Merge remote-tracking branch 'upstream/main' into feature/entities

6652351

use mermaid diagrams

362280b

address the leftover comments

a1746fe

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) December 2, 2024 00:04 Active

IchHabeHunger54 marked this pull request as ready for review December 2, 2024 00:10

IchHabeHunger54 requested a review from ChampionAsh5357 December 2, 2024 00:10

lukebemish reviewed Dec 2, 2024

View reviewed changes

docs/entities/livingentity.md Show resolved Hide resolved

address luke's comment

887ed98

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) December 2, 2024 16:15 Active

XFactHD requested changes Dec 14, 2024

View reviewed changes

address xfact's comments

8e8774d

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) December 14, 2024 17:12 Active

dphaldes reviewed Dec 14, 2024

View reviewed changes

XFactHD reviewed Dec 15, 2024

View reviewed changes

ChampionAsh5357 requested changes Jan 10, 2025

View reviewed changes

neoforged-automation bot added the needs rebase This Pull Request needs to be rebased before being merged label Jan 10, 2025

IchHabeHunger54 added 3 commits January 11, 2025 00:19

address champ's comments, pt 1

77247ba

Merge remote-tracking branch 'origin/main'

fbc75e4

Merge branch 'main' into feature/entities

bf4efbe

# Conflicts: # docs/resources/client/models/bakedmodel.md # docs/resources/server/conditions.md

neoforged-automation bot removed the needs rebase This Pull Request needs to be rebased before being merged label Jan 10, 2025

neoforged-pages-deployments bot deployed to neoforged-docs-previews (Preview) January 10, 2025 23:31 Active

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Entity docs #171

Entity docs #171

IchHabeHunger54 commented Oct 3, 2024 •

edited

Loading

XFactHD left a comment

XFactHD Dec 14, 2024

IchHabeHunger54 Dec 14, 2024

XFactHD Dec 14, 2024

XFactHD Dec 14, 2024

XFactHD Dec 14, 2024

dphaldes Dec 11, 2024

ChampionAsh5357 Jan 10, 2025

XFactHD Dec 15, 2024

ChampionAsh5357 left a comment

ChampionAsh5357 Jan 10, 2025

IchHabeHunger54 Jan 10, 2025

ChampionAsh5357 Jan 10, 2025

ChampionAsh5357 Jan 10, 2025

IchHabeHunger54 Jan 10, 2025

ChampionAsh5357 Jan 11, 2025

ChampionAsh5357 Jan 10, 2025

neoforged-automation bot commented Jan 10, 2025

		EntityRenderer-->ArrowRenderer;
		EntityRenderer-->LivingEntityRenderer;

		Natural spawning is performed every tick for entities where `MobCategory#isFriendly()` is true, and every 400 ticks (\= 20 seconds) for entities where `MobCategory#isFriendly()` is false. If `MobCategory#isPersistent()` returns true, this process additionally also happens on chunk generation.

		For each chunk and mob category, it is checked whether there are less than `MobCategory#getMaxInstancesPerChunk() * loadedChunks / 289` in the world. Additionally, for each chunk, it is required that there are less than `MobCategory#getMaxInstancesPerChunk()` entities of that `MobCategory` near at least one player (near means that the distance between mob and player \<\= 128) for spawning of that `MobCategory` to occur.

Entity docs #171

Are you sure you want to change the base?

Entity docs #171

Conversation

IchHabeHunger54 commented Oct 3, 2024 • edited Loading

XFactHD left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ChampionAsh5357 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

neoforged-automation bot commented Jan 10, 2025

IchHabeHunger54 commented Oct 3, 2024 •

edited

Loading