Please note: Feedback should be submitted through GitHub for issues or suggestions, or through my Twitter (https://twitter.com/legendblade) for all other interaction. Messages through CF are likely to be ignored. Thank you.

Needs, Wants, and Desires (or Needs for short) is a work of ~~love~~ ~~like~~ insanity borne from a desire to allow Minecraft pack makers to have the tools available to them to define arbitrary stats and stat systems that they can use to differentiate their pack, and help bring their world alive.

At a core level, it could be seen as a spiritual successor to mods like Nutrition, or in some aspects, Tough as Nails, because both the core nutrition system from Nutrition, and the temperature system from TAN could be recreated through the Needs system. However, the actual possibilities for systems that could be created through Needs are much larger and, in many ways, much more complicated than that - you can start as simple as one single stat that tracks along with the number of steps the player has taken, to entire stat trees that all interconnect and provide distinctions and drawbacks as the player gains (or loses) levels.

Read more over at https://legendblade.github.io/needs/

Overview

There are a couple of major topics that you will need to know when creating needs.


Need Types

Needs can be custom - meaning that it's brand new functionality being added - or they can be associated with an already-existing stat - some examples which are included by default are a player's max health, or the amount of sunlight they're currently receiving.

Mixins

Needs by themselves are generally hidden, background things that the player can't see. Mixins can help resolve that by adding specific functionality, such as notifying the user with a chat message when they change levels, or displaying information in the UI.

Mixins are in a broad sense functionality that can be shared across needs and mixed-in when you want to use that functionality.

Manipulators

While needs that are based on existing stats - such as health, food, and breath - and are changed by outside forces, your custom needs will need to know how and when to change. Manipulators can provide that functionality by allowing you to define what affects a particular need and how.

However, manipulators don't only apply to custom needs - you can also apply them to any need that isn't read-only; say you wanted to make the player regenerate health when they first enter sunlight - just use the onNeedChanged manipulator to link up the sunlight need with the health need. But maybe that's too nice, and instead you want to... convince the player to be more passive, you could use the holdingmanipulator to say that anytime they're holding a sword or axe, you want to decrease their health by a certain amount - you can do that too.

Conditional Manipulators

If the basic manipulators aren't enough, there are also the Conditional Manipulators, which represent basic logical operators - namely and, or, not, and xor, and allow you to combine together one or more triggers with a collection of conditions to test when triggered.

Manipulators which can be used as a trigger will be marked with Trigger and can be used in the triggers property of a conditional manipulator.

Likewise, manipulators which can be used as a condition will be marked with Condition and can be used in the conditions property of the and, or, and xor conditional manipulators, and the condition property of the not conditional manipulator. Every conditional manipulator is also a condition itself, so you can nest multiple layers of conditions in order to fully define the conditions you want things to run under.

Lastly, the amount expression of the individual conditional manipulators provides access to both any value from the source trigger, as well as the matched condition(s), which can be used to further tailor how things interact.

Levels

Okay, so you have a need, and that's cool, but you want to affect the player in certain ways when they're at a certain level - take the idea that spawned this mod: nutritition (or, specifically: Nutrition, the mod). You want to apply buffs when the player is at high nutritional values, and apply debuffs when they're at low values. That's where levels come into play.

And if you associate the ui mixin, you even get nice looking bars showing you where a particular level starts and ends:

Like mixins and manipulators - levels aren't only for your own custom needs - you can assign levels to any need, including read-only needs. So go forth, don't let your dreams be dreams, add some levels to the moonPhase need, and make the player a wereparrot during the full mooon.




Actions

Levels by themselves are cool, right? I mean, look at those slick UI bars. Okay, but maybe you want the levels to do something beyond just looking pretty - that's where actions come into play.

Each action defines something that happens - either once, or continuously while the player is at the level the action is assigned to - in order to breathe some life into your levels - possibly literally, you can use the adjustNeed action to target the player's breath need.





Expressions

Expressions are a way to make things more dynamic. On a basic level, most manipulators, rather than just taking in a value that they adjust their associated need by, can instead take a mathematical expression like this:

current / 2

... or this:

min(current,4) + max(-2,need(Some Other Need))

Or anything else you can find over at http://mathparser.org/mxparser-math-collection/in order to let you have full control over how things work.