net.risingworld.api.objects.custom

Class CustomItem

java.lang.Object

net.risingworld.api.objects.custom.CustomItem

public class CustomItem
extends java.lang.Object

A class which represents a custom item, or more precisely, a custom item definition. It's possible to set a custom model, icon and animations for the item.
When creating a new custom item definition, make sure you register it to the server.

See Also:

Server.registerCustomItem(net.risingworld.api.objects.custom.CustomItem)

Example: Create a new custom item (put this into the "onEnable()" method)

1	//Create a custom item and assign a unique UUID to it
2	CustomItem item = new CustomItem("myCustomUUIDWhichHasToBeUnique", "magicpickaxe");
3
4	//Load the model and texture
5	item.setModel(new ModelInformation(getPath() + "/pickaxe.obj"), new ImageInformation(getPath() + "/pickaxe.dds"), 0.5f);
6
7	//Assign an icon (which is visible in the inventory, for example)
8	item.setIcon(new ImageInformation(getPath() + "/pickaxe_icon.png");
9
10	//Max stack size for this item (1 == only 1 item per slot)
11	item.setMaxStacksize(1);
12
13	//Set an idle animation for this item
14	item.setPlayerIdleAnimation(Animation.Pickaxe1Idle);
15
16	//Easy way to make the item behave like a tool or weapon:
17	//Just assign an existing HitDamageDefinition. In this case, we use the definition of the steel pickaxe
18	item.setHitDamageDefinition(Definitions.getHitDamageDefinition("pickaxesteel"));
19
20	//You can easily set up a multiplier for the damage, e.g. 0.5f for half damage, 2.0f for double damage etc.
21	item.setHitDamageFactor(2f);
22
23	//Set localized item names. Alternatively you can just provide a single universal name
24	item.setLocalizedNames("en=Magic Pickaxe", "de="Magische Spitzhacke");
25
26	//Set up a primary item action. Trigger delay is 0.5, i.e. 0.5 seconds after the animation started
27	//a "hit" will be triggered.
28	//We don't need custom behaviour in this case so don't assign an "Action" (null)
29	item.setPrimaryActioni(Animation.Pickaxe1, 0.5f, null);
30
31	//Special case: We want our magic pickaxe to trigger a firework effekt when using the
32	//secondary mouse button. To achieve that, we need an "Action". You can use a lambda
33	//expression to easily set up an "Action". The "Action" is triggered after 0.5 seconds
34	//(in this case), and the current RayCastCollision as well as the player object is
35	//passed as argument
36	item.setSecondaryAction(Animation.Pickaxe1, 0.5f, (player, collision) -> {
37	//Check if collision != null
38	if(collision != null && collision.hasCollision()){
39	//Trigger a firework effect at the hit position
40	getWorld().triggerFirework(collision.getCollisionPoint(), 0.1f, 0xFF0000FF, 0xFFFF00FF, 0xFFFFFFFF, false);
41	}
42	});
43
44	//Now it gets tricky: We need to set up the item position and rotation in the player hands.
45	//You can adjust it ingame by typing "debugitem" into console, this allows you to use the
46	//arrow keys to move the item in the player hand (hold shift to rotate it). The coordinates
47	//are then output to the console
48	item.setItemPosition(0f, 0f, 0f);
49	item.setItemRotation(0f, 0f, 0f, 1f);
50
51	//We can do the same with the "body position". This is useful to take more control of the
52	//position of the player hands in first person view. Type "debugplayerbody" into console
53	//(similar to "debugitem") to manipulate the player body position (if "debugitem" is active,
54	//make sure to disable it first)
55	item.setFPBodyPosition(0f, 0f, 0f);
56	item.setFPBodyRotation(0f, 0f, 0f, 1f);
57
58	//Finally register the item to the server. It's recommendable to not modify any item properties
59	//once the item has been registered to the server
60	getServer().registerCustomItem(item);

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	CustomItem.Action An "action" interface which is called for primary/secondary action.
static class	CustomItem.Hand Determines in which hand the item is held (more precisely, which hand the item gets attached to)
class	CustomItem.Variation Represents an item "variation".

Constructor Summary

Constructors

Constructor and Description
CustomItem(java.lang.String uuid, java.lang.String name) Creates a new custom item, or more precisely, meta data for a custom item.

Method Summary

Modifier and Type	Method and Description
Vector3f	getFPBodyPosition()
Quaternion	getFPBodyRotation()
CustomItem.Hand	getHand()
Definitions.HitDamageDefinition	getHitDamageDefinition()
float	getHitDamageFactor()
ImageInformation	getIcon() Gets the ImageInformation object which is used as icon for this custom item.
Vector3f	getItemPosition() Sets the "offset" of the item in the player hands.
Quaternion	getItemRotation() Sets the rotation of the item in the player hands.
java.lang.String[]	getLocalizedNames()
int	getMaxStacksize() Gets the max amount of items that can be stacked.
ModelInformation	getModel() Gets the ModelInformation object which is used for this custom item.
float	getModelSize() Gets the model size.
java.lang.String	getName() Gets the item name.
int	getNumberOfVariations()
Animation	getPlayerIdleAnimation()
Animation	getPlayerPrimaryAnimation()
Animation	getPlayerSecondaryAnimation()
CustomItem.Action	getPrimaryAction()
float	getPrimaryActionDelay()
CustomItem.Action	getSecondaryAction()
float	getSecondaryActionDelay()
ImageInformation	getTexture() Gets the ImageInformation object which is used as texture for this custom item.
java.lang.String	getUUID() Gets the UUID of this item.
CustomItem.Variation[]	getVariations()
void	setFPBodyPosition(float x, float y, float z) Sets the "offset" of the player body in first person view.
void	setFPBodyPosition(Vector3f position) Sets the "offset" of the player body in first person view.
void	setFPBodyRotation(float x, float y, float z, float w) Sets the rotation of the player body in first person view.
void	setFPBodyRotation(Quaternion rotation) Sets the rotation of the player body in first person view.
void	setHand(CustomItem.Hand hand) Determines in which hand the item is being held (left hand, right hand, no hand).
void	setHitDamageDefinition(Definitions.HitDamageDefinition definition) Sets a hit damage definition for this item.
void	setHitDamageFactor(float factor) Sets the damage factor for hits.
void	setIcon(ImageInformation icon) Sets the item icon (visible in inventory, chests, hotbar etc).
void	setItemPosition(float x, float y, float z)
void	setItemPosition(Vector3f position)
void	setItemRotation(float x, float y, float z, float w)
void	setItemRotation(Quaternion rotation)
void	setLocalizedNames(java.lang.String... names) Sets a (localized) name of the item.
void	setMaxStacksize(int stacksize) Sets the max amount of items that can be stacked.
void	setModel(ModelInformation model, ImageInformation texture, float modelSize) Sets a model for this item, including the according texture.
void	setPlayerIdleAnimation(Animation animation) Sets the idle animation of the player when this item is equipped.
void	setPrimaryAction(Animation primaryAnimation, float triggerDelay, CustomItem.Action action) Defines the (custom) primary action and animation for this item.
void	setPrimaryFPBodyPosition(float x, float y, float z) Sets the "offset" of the player body in first person view.
void	setSecondaryAction(Animation secondaryAnimation, float triggerDelay, CustomItem.Action action)
void	setVariation(int variation, ImageInformation texture, ImageInformation icon)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CustomItem

public CustomItem(java.lang.String uuid,
                  java.lang.String name)

Creates a new custom item, or more precisely, meta data for a custom item.

Parameters:

uuid - a unique UUID for the item. It's highly important that this UUID never changes, and it's also important to make sure that there are no collisions with the UUID of another item. For example, you could use the package name as part of the UUID: "com.yourname.pluginname.items.pickaxesteel"

name - the internal item name, e.g. "pickaxe1" or "magicaxe". This is not the name that's shown to the player (see setLocalizedNames(java.lang.String...) for that). Allowed characters: A-Z, a-z, 0-9 and _

Method Detail

setMaxStacksize

public void setMaxStacksize(int stacksize)

Sets the max amount of items that can be stacked. Must not be lower than 1 or higher than 100. Default stack size is 1.

Parameters:

stacksize - the new stack size.

getMaxStacksize

public int getMaxStacksize()

Gets the max amount of items that can be stacked.

Returns:

the max stack size.

setModel

public void setModel(ModelInformation model,
                     ImageInformation texture,
                     float modelSize)

Sets a model for this item, including the according texture.

Parameters:

model - the ModelInformation object which represents the model file.

texture - the ImageInformation object, which represents the texture image.

modelSize - the model scale factor. Default is 1.0f

Example:

1	//Create a new custom item object
2	CustomItem item = new CustomItem("net.risingworld.api.customitems.tools.hoe1", "oldhoe_1", Type.Item);
3
4	//Load the ModelInformation (model) and ImageInformation (texture)
5	ModelInformation model = new ModelInformation(getPath() + "/" + "items/hoe/hoe1.obj");
6	ImageInformation image = new ImageInformation(getPath() + "/" + "items/hoe/hoe_512x512.dds");
7
8	//Assign the model and texture to the item (size 0.5)
9	item.setsModel(model, image, 0.5f);

setIcon

public void setIcon(ImageInformation icon)

Sets the item icon (visible in inventory, chests, hotbar etc). It's highly recommendable to use a small texture for this, default game icon resolution is 128x128.

Parameters:

icon - the ImageInformation object, which represents the icon for this item.

getModel

public ModelInformation getModel()

Gets the ModelInformation object which is used for this custom item. If this is an item, the player will hold this model in his hands while equipped (e.g. a sword). If this is an object, the model is the actual object that will be placed in the world (e.g. a table).

Returns:

the ModelInformation object, i.e. the actual 3D model.

getTexture

public ImageInformation getTexture()

Gets the ImageInformation object which is used as texture for this custom item.

Returns:

the ImageInformation object, which represents the texture.

getIcon

public ImageInformation getIcon()

Gets the ImageInformation object which is used as icon for this custom item.

Returns:

the ImageInformation object, which represents the item icon (which is seen in the inventory, for example).

setVariation

public void setVariation(int variation,
                         ImageInformation texture,
                         ImageInformation icon)

getNumberOfVariations

public int getNumberOfVariations()

getVariations

public CustomItem.Variation[] getVariations()

setHand

public void setHand(CustomItem.Hand hand)

Determines in which hand the item is being held (left hand, right hand, no hand).

Parameters:

hand - the hand in which the item is being held. Set to Hand.None if you don't want the player to hold the item in his hands.

getHand

public CustomItem.Hand getHand()

getUUID

public java.lang.String getUUID()

Gets the UUID of this item.

Returns:

the UUID, as a String.

setLocalizedNames

public void setLocalizedNames(java.lang.String... names)

Sets a (localized) name of the item. While the actual item name is only used for internal purposes, this is the name which is actually shown to the user. E.g. if the internal item name is "magic_pickaxe_1", you could set "Magical Pickaxe (Lvl 1)" as localized english name for the item. Multiple languages are supported
Currently supported languages: en (english), de (german)

Parameters:

names - an array of all localized names for this item. If you want to support multiple languages, you have set the name like this: "en=Pickaxe" or "de=Spitzhacke" etc. example [Set an english, german and french item name] CustomItem item = new CustomItem("123124124123123_customItems_pickaxe", "pickaxe", Type.Item); item.setLocalizedNames(new String[]{"en=Pickaxe", "de=Spitzhacke", "fr=Pioche"}); example [Set a universal item name, which is used in all languages] CustomItem item = new CustomItem("9d8jsxK3n2nsiuhME3_sword1", "sword", Type.Item); item.setLocalizedNames(new String[]{"Mighty Sword"});

getLocalizedNames

public java.lang.String[] getLocalizedNames()

setItemPosition

public void setItemPosition(Vector3f position)

setItemPosition

public void setItemPosition(float x,
                            float y,
                            float z)

setItemRotation

public void setItemRotation(Quaternion rotation)

setItemRotation

public void setItemRotation(float x,
                            float y,
                            float z,
                            float w)

getItemPosition

public Vector3f getItemPosition()

Sets the "offset" of the item in the player hands.

Returns:

the item offset.

getItemRotation

public Quaternion getItemRotation()

Sets the rotation of the item in the player hands.

Returns:

the item rotation.

setFPBodyPosition

public void setFPBodyPosition(Vector3f position)

Sets the "offset" of the player body in first person view. Default offset is 0, 0, 0. Does not have an effect on third person view.

Parameters:

position - the offset of the player body (in first person view).

setFPBodyPosition

public void setFPBodyPosition(float x,
                              float y,
                              float z)

Sets the "offset" of the player body in first person view. Default offset is 0, 0, 0. Does not have an effect on third person view.

Parameters:

x - the x offset of the player body (in first person view).

y - the y offset of the player body (in first person view).

z - the z offset of the player body (in first person view).

getFPBodyPosition

public Vector3f getFPBodyPosition()

setFPBodyRotation

public void setFPBodyRotation(Quaternion rotation)

Sets the rotation of the player body in first person view. Default rotation is 0, 0, 0, 1 (identity quaternion). Does not have an effect on third person view.

Parameters:

rotation - the rotation of the player body (in first person view).

setFPBodyRotation

public void setFPBodyRotation(float x,
                              float y,
                              float z,
                              float w)

Sets the rotation of the player body in first person view. Default rotation is 0, 0, 0, 1 (identity quaternion). Does not have an effect on third person view.

Parameters:

x - the x rotation component of the player body (in first person view).

y - the y rotation component of the player body (in first person view).

z - the z rotation component of the player body (in first person view).

w - the w rotation component of the player body (in first person view).

getFPBodyRotation

public Quaternion getFPBodyRotation()

setPrimaryFPBodyPosition

public void setPrimaryFPBodyPosition(float x,
                                     float y,
                                     float z)

Sets the "offset" of the player body in first person view. Default offset is 0, 0, 0. Does not have an effect on third person view.

Parameters:

x - the x offset of the player body (in first person view).

y - the y offset of the player body (in first person view).

z - the z offset of the player body (in first person view).

getName

public java.lang.String getName()

Gets the item name.

Returns:

the item name.

getModelSize

public float getModelSize()

Gets the model size. Default size is 1.0f

Returns:

the size of the item model.

setHitDamageDefinition

public void setHitDamageDefinition(Definitions.HitDamageDefinition definition)

Sets a hit damage definition for this item. This causes this item to behave like a regular (vanilla) tool or melee weapon, i.e. this item triggers regular hit events (like PlayerHitEvent, PlayerDestroyTerrainEvent etc). In other words, you can turn this item easily into a sword or pickaxe with the same behaviour like the vanilla counterparts.

Parameters:

definition - the hit damage definition (see Definitions.getHitDamageDefinition(java.lang.String)). Alternatively you can create a new damage definition (currently not supported).

Example: Create a custom pickaxe which behaves like the vanilla steel pickaxe

1	//Create custom item with unique UUID and name
2	CustomItem item = new CustomItem("1211212312355667_custom_diamondpickaxe", "diamondpickaxe", Type.Item);
3
4	//Set model, texture and icon for the item
5	ModelInformation model = new ModelInformation(getPath() + "/diamondPickaxe.obj");
6	ImageInformation texture = new ImageInformation(getPath() + "/diamondTex.jpg");
7	ImageInformation icon = new ImageInformation(getPath() + "/diamondIcon128x128.jpg");
8
9	//Assign model and texture to item
10	item.setModel(model, texture, 1f);
11
12	//Assign icon
13	item.setIcon(icon);
14
15	//Set Idle Animation
16	item.setPlayerIdleAnimation(Animation.Pickaxe2Idle);
17
18	//Set Primary Action (triggers after 0.5 seconds, no additional actions)
19	item.setPrimaryAction(Animation.Pickaxe2, 0.5f, null);
20
21	//Get HitDamageDefinition of vanilla steel pickaxe
22	Definitions.HitDamageDefinition def = Definitions.getHitDamageDefinition("pickaxesteel");
23
24	//Assign def to this item
25	item.setHitDamageDefinition(def);
26
27	//Register custom item to server
28	getServer().registerCustomItem(item);

getHitDamageDefinition

public Definitions.HitDamageDefinition getHitDamageDefinition()

setHitDamageFactor

public void setHitDamageFactor(float factor)

Sets the damage factor for hits. Only works if a HitDamageDefinition was set (see setHitDamageDefinition(net.risingworld.api.utils.Definitions.HitDamageDefinition)). The damage factor multiplies the default damage of the HitDamageDefinition by the given value. Default value is 1.0f

Parameters:

factor - the new damage factor, e.g. when setting 2.0f, the item will deal the double amount of damage.

See Also:

setHitDamageDefinition(net.risingworld.api.utils.Definitions.HitDamageDefinition)

getHitDamageFactor

public float getHitDamageFactor()

setPlayerIdleAnimation

public void setPlayerIdleAnimation(Animation animation)

Sets the idle animation of the player when this item is equipped. Default animation is Animation.Weapon1HandIdle.

Parameters:

animation - the player idle animation when holding this item in his hands.

getPlayerIdleAnimation

public Animation getPlayerIdleAnimation()

setPrimaryAction

public void setPrimaryAction(Animation primaryAnimation,
                             float triggerDelay,
                             CustomItem.Action action)

Defines the (custom) primary action and animation for this item.

Parameters:

primaryAnimation - the primary player animation.

triggerDelay - the delay until a "hit" is triggered (usually somewhere between 0 and 0.5 seconds).

action - an optional custom action that will be triggered.

setSecondaryAction

public void setSecondaryAction(Animation secondaryAnimation,
                               float triggerDelay,
                               CustomItem.Action action)

getPlayerPrimaryAnimation

public Animation getPlayerPrimaryAnimation()

getPrimaryActionDelay

public float getPrimaryActionDelay()

getPlayerSecondaryAnimation

public Animation getPlayerSecondaryAnimation()

getSecondaryActionDelay

public float getSecondaryActionDelay()

getPrimaryAction

public CustomItem.Action getPrimaryAction()

getSecondaryAction

public CustomItem.Action getSecondaryAction()