Creating your first entity tutorial is missing some information

[markaull]

I just completed the "Creating Your First Entity" part of the Fabric documentation. The following things were unclear or missing from the documentation:

1. After using the Template mod generator, files must be in the correct directories:
   \src\client\java\com\example\docs\client\mixin\ExampleClientMixin.java
   \src\client\java\com\example\docs\entity\ExampleModCustomEntityClient.java
   \src\client\java\com\example\docs\entity\animation\MiniGolemAnimations.java
   \src\client\java\com\example\docs\entity\client\EntityClient.java
   \src\client\java\com\example\docs\entity\client\mixin\ExampleClientMixin.java
   \src\client\java\com\example\docs\entity\model\MiniGolemEntityModel.java
   \src\client\java\com\example\docs\entity\model\ModEntityModelLayers.java
   \src\client\java\com\example\docs\entity\renderer\MiniGolemEntityRenderer.java
   \src\client\java\com\example\docs\entity\state\MiniGolemEntityRenderState.java
   \src\client\resources\entity.client.mixins.json
   \src\client\resources\assets\example-mod\textures\entity\mini_golem_small.png
   \src\main\java\com\example\docs\ExampleMod.java
   \src\main\java\com\example\docs\entity\MiniGolemEntity.java
   \src\main\java\com\example\docs\entity\ModEntityTypes.java
   \src\main\java\com\example\docs\entity\attribute\EntityAttributesGameTest.java
   \src\main\java\com\example\docs\entity\attribute\ExampleModAttributes.java
   \src\main\java\com\example\docs\entity\attribute\ModAttributes.java
   \src\main\java\com\example\docs\entity\mixin\ExampleMixin.java
   \src\main\java\com\example\docs\mixin\ExampleMixin.java
   \src\main\resources\entity.mixins.json
   \src\main\resources\fabric.mod.json
   \src\main\resources\assets\example-mod\icon.png

2. Mod ID must match between ExampleMod.java
   public static final String MOD_ID = "example-mod";
   and fabric.mod.json
   "name": "example-mod",

3. Entry points must be set correctly in fabric.mod.json, template client file should be removed
   "entrypoints": {
   "main": [
   "com.example.docs.ExampleMod"
   ],
   "client": [
   "com.example.docs.entity.ExampleModCustomEntityClient"
   ]
   },

4. Code to register the entity must be added to the main entry point function (or a file for the main entry point should be provided):
   ModEntityTypes.registerModEntityTypes();
   ModEntityTypes.registerAttributes();

5. I recommend adding options for auto-spawning and attack goals because those are common entity functions:
   MobCategory.CREATUR in ModEntityTypes and
   BiomeModifications.addSpawn(
   BiomeSelectors.foundInOverworld(),
   MobCategory.CREATURE,
   ModEntityTypes.MINI_GOLEM,
   20,
   2,
   4
   );
   in main onInitialize

    this.goalSelector.addGoal(1, new MeleeAttackGoal(this, (double)1.0F, true));
    this.targetSelector.addGoal(1, new NearestAttackableTargetGoal(this, Mob.class, 5, false, false, (target, var1) -> target instanceof Enemy));
   

   in registerGoals
   and
   .add(Attributes.ATTACK_DAMAGE, 1);
   in AttributeSupplier.Builder

[sylv256]

One through four are covered by earlier pages.

[markaull]

One through four are covered by earlier pages.

I've written documentation for things before, and it's painfully clear that when you know something well, it can be hard to think of all the things that someone won't know or understand or put together when they're starting out, so it's helpful to get feedback about what a document is missing. And as someone new to Minecraft mods, I can tell you my experience, which I hoped would be helpful.

And I can tell you that I started with the "developer guide" section to get the IDE and tools set up, then moved to the "entity" section, assuming I wouldn't need to do the "items", "blocks", and "fluids" first. And just now, I looked at the item section, and it doesn't look like it contains any additional detail. The "project structure" page has sections that look similar to what I wrote, but they're very abstract, and I needed something very explicit and concrete.

For example, when "project structure" says

"src/main/java
The src/main/java folder is used to store the Java source code for your mod - it exists on both the client and server environments."

I needed ChatGPT to figure out that it should say "add these specific subdirectories to /main/java, and put these files in these specific subdirectories.

Or when "project structure" says

"fabric.mod.json:
entrypoints: The entrypoints that your mod provides, such as main or client."

it was not clear that that meant "search through the provided files to see whether there's a provided entry point or not; in this case, change the json to point at the client one, but you have to use the main one from the template and add some of the register functions
ModEntityTypes.registerModEntityTypes();
ModEntityTypes.registerAttributes();
but not "registerGoals" because it gets called automatically.

So I was trying to be helpful by collecting all the things that were unclear enough that I got stuck for a while and/or needed AI assistance with.

Also, the texture filename "mini_golem_small.png" doesn't match the texture filename in the path specified in the text: assets/example-mod/textures/entity/mini_golem.png. I didn't notice that issue because I've worked with Android apps, which handle different sized icons like that intentionally.

[its-miroma]

Thank you so much for your perspective! I am creating a new label for issues related to onboarding, because this is an aspect that I want the Docs to improve on gradually. Please please feel free to provide your rare feedback!

I'll provide some possible solutions, and I'd like you to tell me if they would be helpful, and to suggest your own.

After using the Template mod generator, files must be in the correct directories

Just for feedback: are you aware of the "Files Referenced" section on the right aside of each page? It shows the file names, but when you hover over them it shows the full file path:

(The ... aren't a cut off, they are the package which you may adapt to your own project; the docs use com.example.docs but we might want to change that to make it clearer. Maybe net.fabricmc.docs. Anyway, you can use your own reverse TLD, for a domain you own, for example io.github.markaull.your_awesome_mod)

If you click on any of those files, you will see the full source code of that class (which may include code unrelated to the specific page you are working on).

Mod ID must match between ExampleMod.java [...] and fabric.mod.json

I believe that the template mod generator already generates both files with the ID you chose, so I'm guessing that you later wanted to change the ID on your own? Maybe MCDev should notice this and prompt you to change the MOD_ID also.

Also, again for feedback: are you aware that you can name that class whatever you want? ExampleMod is what we used because this is the example mod, but if your mod is called "Your Awesome Mod" the class name should be YourAwesomeMod.

I am thinking of adding a new component in the Docs, where you can customize the Docs' names on your end to correspond to your project. So, for example, you can give your mod id and every reference to example-mod will be replaced with your-awesome-mod.

I am also thinking of making it so each code block that comes from a file also says where it comes from. In other words: you will be able to see that this code block comes from a certain file, so you know where to place it.

Entry points must be set correctly in fabric.mod.json. Code to register the entity must be added to the main entry point function

Yea, that is completely missing from the Entities page. We should create a template for any "Creating Your First X" article where we mention that we have to have the ModX and ModXIds classes, the entrypoint, the initializer, and all the pages must follow that pattern.

The "project structure" page has sections that look similar to what I wrote, but they're very abstract, and I needed something very explicit and concrete.

I 100% agree. I am thinking of adding a graphic of a mod folder structure, where each file can be described. We also have an issue open (#230) about the distinction between server-side code (src/main/java) and client-side code (src/client/java), which should also be mentioned in that page in greater detail.

search through the provided files to see whether there's a provided entry point or not

I will need someone else to answer this, but perhaps you do not need an entrypoint for each file, you can just have one for the client and one for the server. Correct me if I'm wrong, anyone.

Also, the texture filename "mini_golem_small.png" doesn't match the texture filename in the path specified in the text: assets/example-mod/textures/entity/mini_golem.png.

I have noticed that issue, and it's because the DownloadEntry component needs two different images: one for the preview that you see on the page, and one is what gets downloaded. That means that they use two different file names. I am working on a refactor that shall resolve this, but it's a little bit larger and won't come for a while. In the meantime, the preview should be named mini_golem_big.png, so that the downloaded file can be mini_golem.png.

[markaull]

when you hover over them it shows the full file path:

I did not know that.

The ... aren't a cut off, they are the package which you may adapt to your own project

That would not have been obvious; something like [your-package-name] would be better.

I believe that the template mod generator already generates both files with the ID you chose, so I'm guessing that you later wanted to change the ID on your own? Maybe MCDev should notice this and prompt you to change the MOD_ID also

Yes, I generated a template assuming that the name and package wouldn't matter, then realized that every file had things I would need to find-replace, and was concerned that I might break something that way, so I tried to change the package name and didn't find both of them at the same time.

I am also thinking of making it so each code block that comes from a file also says where it comes from. In other words: you will be able to see that this code block comes from a certain file, so you know where to place it

I think that's a good change. I downloaded the files to try to get a working example before really looking at the code, but either order someone works in, it would help to know what code is where.

I will need someone else to answer this, but perhaps you do not need an entrypoint for each file, you can just have one for the client and one for the server. Correct me if I'm wrong, anyone.

What I meant was that the I had to learn that the client entrypoint is in ExampleModCustomeEntityClient.java and that the main entrypoint is in the template file (ExampleMod.java in this case), and initially I didn't know here the client entrypoint was or that there wasn't a main entrypoint in the provided files, so I would have had to search each file to find the entrypoint functions or confirm they weren't there.

[NotNightSky]

What if we make a page or at least a section called "Common Mistakes" or "Troubleshooting" to cover common mistakes that beginners as well as experienced developers make sometimes. (Sorry in advance if this sounds dumb).