Class Level

java.lang.Object

me.tayebyassine.homestead.models.Level

public final class Level
extends Object

Tracks the level and experience of a region.

Regions accumulate experience through various actions and level up according to a quadratic formula: BASE * level^2 + COEFFICIENT * level + CONSTANT.

When a level-up occurs the region owner receives a notification if they are online.

Field Summary

Fields

Modifier and Type	Field	Description
static final double	BASE	Quadratic coefficient for the XP formula.
static final double	COEFFICIENT	Linear coefficient for the XP formula.
static final double	CONSTANT	Constant term for the XP formula.

Constructor Summary

Constructors

Constructor	Description
Level(long regionId)	Create a new level tracker with a generated snowflake ID.
Level(long id, long regionId, int level, long experience, long totalExperience, long createdAt)	Create a level tracker from pre-existing data (deserialization).

Method Summary

Modifier and Type	Method	Description
void	addXp(long amount)	Add experience.
long	getCreatedAt()	Get the creation timestamp.
long	getExperience()	Get the current experience within the level.
int	getLevel()	Get the current level.
double	getProgressPercentage()	Get the progress percentage toward the next level.
@Nullable Region	getRegion()	Get the parent region from the cache.
long	getRegionId()	Get the owning region ID.
String	getRegionName()	Get the parent region's name safely.
long	getTotalExperience()	Get the lifetime experience earned.
long	getTotalXpForCurrentLevel()	Get the total XP required to reach the current level from level 0.
long	getUniqueId()	Get the unique snowflake ID.
static long	getXpForLevel(int level)	Calculate the XP required to reach a given level.
long	getXpForNextLevel()	Get the XP required for the next level-up.
long	getXpProgress()	Get the XP progress toward the next level.
long	getXpRemaining()	Get the XP remaining until the next level.
void	removeXp(long amount)	Remove experience.
void	reset()	Reset the level to 0 and clear all experience.
void	setLevel(int level)	Set the level directly.
void	setRegionId(long regionId)	Set the owning region ID.
void	setXp(long experience)	Set the experience directly.

Methods inherited from class Object

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

Field Details

BASE

public static final double BASE

Quadratic coefficient for the XP formula.

See Also:

• Constant Field Values

COEFFICIENT

public static final double COEFFICIENT

Linear coefficient for the XP formula.

See Also:

• Constant Field Values

CONSTANT

public static final double CONSTANT

Constant term for the XP formula.

See Also:

• Constant Field Values

Constructor Details

Level

public Level(long regionId)

Create a new level tracker with a generated snowflake ID.

Parameters:

regionId - the owning region ID

Level

public Level(long id,
 long regionId,
 int level,
 long experience,
 long totalExperience,
 long createdAt)

Create a level tracker from pre-existing data (deserialization).

Parameters:

id - the snowflake ID

regionId - the owning region ID

level - the current level

experience - the current XP within the level

totalExperience - the lifetime XP earned

createdAt - the creation timestamp

Method Details

getXpForLevel

public static long getXpForLevel(int level)

Calculate the XP required to reach a given level.

Parameters:

level - the target level

Returns:

the XP needed, or 0 for negative levels

getUniqueId

public long getUniqueId()

Get the unique snowflake ID.

Returns:

the level ID

getCreatedAt

public long getCreatedAt()

Get the creation timestamp.

Returns:

the epoch-millis timestamp

getRegionId

public long getRegionId()

Get the owning region ID.

Returns:

the region ID

setRegionId

public void setRegionId(long regionId)

Set the owning region ID.

Parameters:

regionId - the new region ID

getRegion

@Nullable
public @Nullable Region getRegion()

Get the parent region from the cache.

Returns:

the region, or null if not found

getRegionName

public String getRegionName()

Get the parent region's name safely. Returns "?" if not found.

Returns:

the region name

getLevel

public int getLevel()

Get the current level.

Returns:

the level

setLevel

public void setLevel(int level)

Set the level directly. Resets the current experience to zero.

Parameters:

level - the new level (clamped to ≥ 0)

getExperience

public long getExperience()

Get the current experience within the level.

Returns:

the XP

getTotalExperience

public long getTotalExperience()

Get the lifetime experience earned.

Returns:

the total XP

getTotalXpForCurrentLevel

public long getTotalXpForCurrentLevel()

Get the total XP required to reach the current level from level 0.

Returns:

the cumulative XP

getXpForNextLevel

public long getXpForNextLevel()

Get the XP required for the next level-up.

Returns:

the XP needed

getXpProgress

public long getXpProgress()

Get the XP progress toward the next level.

Returns:

the current XP within the level

getXpRemaining

public long getXpRemaining()

Get the XP remaining until the next level.

Returns:

the remaining XP

getProgressPercentage

public double getProgressPercentage()

Get the progress percentage toward the next level.

Returns:

the percentage (0.0 – 100.0)

addXp

public void addXp(long amount)

Add experience. Triggers level-up checks.

Parameters:

amount - the XP to add (ignored if non-positive)

setXp

public void setXp(long experience)

Set the experience directly. Triggers level-up checks.

Parameters:

experience - the new XP value

removeXp

public void removeXp(long amount)

Remove experience. Never goes below zero.

Parameters:

amount - the XP to remove (ignored if non-positive)

reset

public void reset()

Reset the level to 0 and clear all experience.