Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: add documentation about item entities #25

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/feature/entities.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Entity creation starts with an entity class selection. Regardless of the type of
* `Entity` is the most barebones version of an entity. It provides you with a minimal API (and minimal overhead), including spawning packet handling, metadata support, default physics.
* `LivingEntity` extends `Entity` and also allows you to grant your entity liveliness. The type of entity doesn't matter, minestom doesn't restrict you to what Mojang intends. If you give it health, it will have health. This subclass also provides an API to modify the entity's equipment and attributes.
* `EntityCreature` extends `LivingEntity` and also provides you with the navigation and AI API.
* `ItemEntity` extends `Entity` and provides you with the ability to spawn items in the world.

If none of the above fits your requirements, you are free to use any of these classes as an ancestor for your own entity class implementation. It could be viable in cases when you need to handle physics or overwrite already presented methods. There are several examples in Minestom repository itself: `Player` that extends `LivingEntity` and handles equipment and a bunch of other things; `EntityProjectile` that extends `Entity` and has its own physics and collision code.

Expand All @@ -35,6 +36,17 @@ EntityCreature boat = new EntityCreature(EntityType.BOAT);
boat.setInstance(instance, spawnPosition); // actually spawning a boat
```

Creating an item entity:

```java
Instance instance = ...; // instance to spawn an item in
Pos spawnPosition = new Pos(0D, 42D, 0D);
ItemEntity item = new ItemEntity(ItemStack.of(Material.DIAMOND_SWORD));
item.setInstance(instance, spawnPosition); // actually spawning an item
```

> For more info on adding functionality to the item entity, view the [demo](https://github.com/Minestom/Minestom/blob/32735340d723dd44733fe1941b138dfa4ecf6d3b/demo/src/main/java/net/minestom/demo/PlayerInit.java#L74C1-L92C15).

## Entity Meta

Once you have selected a class for an entity and instantiated it, you can retrieve it's metadata using `Entity#getEntityMeta()`. Casting this to the proper type, depending on the entity type you specified on instantiation, allows you to change the way your entity will be displayed on clients.
Expand Down