Skip to content
This repository has been archived by the owner on Apr 3, 2024. It is now read-only.

Configuration Reference

Jump to bottom
1cec0ld edited this page Jun 11, 2012 · 74 revisions

TABLE OF CONTENTS:

  • Before You Read

  • The ModDamage Elements Tree

  • Section A: Events reference - "What Damage-related Events Can I Change With ModDamage?"

  • Section B: Routines - "How do I tinker with these damage events?"

    • [B.01]: Base calculation strings

    • [B.02]: Conditional calculation strings

    • [B.03]: Effect calculation strings

    • [B.04]: Routine Index: Exhaustively Listed Here

  • Section C: Topics in MD - "What can I evaluate in MD?

  • Section D: Miscellaneous Config and FAQs

Before You Read

While the tutorials certainly provide a good foundation for MD usage, it's not exhaustive, nor should it be. This page is meant to be a primary source of reference for explorative users or those who have questions about ModDamage features and/or how to use them.

For any MD config, you can verify that your YAML is valid here. This is helpful for people new to YAML, and a must for bug reporting.

Some of the syntax notation in individual routine entries may not necessarily be intuitive - it is necessary, then, to clarify what this notation means. An exhaustive list is as follows:

  • {armorsetalias} - a valid armor/equipment set interpreted by ModDamage, or an alias comprised of armorsets. See the second tutorial for more information.

  • {biomealias} - a valid Biome according to the Bukkit enum, or an alias comprised of these.

  • {comparison} - a comparison operator for the comparison conditional. Possible values can be found at the appropriate area in the ModDamage source.

  • {conditionalalias} - a Conditional string, which is of the form $condition [$operator $condition]...

  • {environment} - a valid Environment according to the Bukkit enum.

  • {groupalias} - a group defined in a Permissions implementation supported by ModDamage, or a group alias comprised of these. These are NOT validated by ModDamage upon load, so exercise caution with these values.

  • {itemalias} - Basically a Material with an amount associated. The format is $material*somenumber (no material aliases). It's worth noting that you can use dynamic numbers here.

  • {materialalias} - a valid Material according to the Bukkit enum.

  • {logical} - a logical operator for a conditional. Located in source here.

  • {messagealias} - a valid Message alias reference, a nested set of messages, or single message string. If using the latter, it's recommended to use double-quotes instead of single quotes around your Message routine to ensure that your message is read properly. Some examples:

Damage:
    - 'if (attacker.type.player and attacker.haspermission.customperms.mobcrits) and target.type.mob and chance.10':
        - 'mult.2'
        - 'message.attacker': "You have dealt a crit!"
Spawn:
    - 'if entity.type.player':
        - 'message.entity':
            - '&9MOTD'
            - '&9----------'
            - "&2Protip:&9 don't suck."
            - "&9One man's trash is another man's treasure."

  • {typealias} - a string that corresponds to a type of entity in ModDamage. See the ModDamage Elements tree for more information.

  • {worldalias} - a world name in your Bukkit server, or an alias comprised of these. World names are validated upon loading, and will generate a warning that cannot be muted if you attempt to use a world name that does not exist.

The ModDamage Elements Tree

The ModDamageElement class no longer exists. Most of it became EntityType, but there is also DamageType and HealType.

SECTION A - "What Damage-related Events Can I Change With ModDamage?"

A.01 - Damage

Damage is an event fired whenever...well...whenever something living takes damage! Manipulating this event is simple. Use routines to alter the event's value. Valid entities for this event are Attacker, Projectile (if it exists), and Target.

Damage events are demonstrated from the very beginning of the MD tutorials.

A.02 - Death

Death routines are also self-explanatory. Unlike the Damage event, there's no way to change the outcome of this event - the entity's going to die, no matter what value-manipulation routines you use. The most useful routines here will likely be Message or Calculation routines that do something interesting to the last attacker or the event's world. Valid entities are the same as in Damage - Attacker, Projectile (if it exists), and Target.

A.03 - Food

Food routines are fired whenever a player consumes an item.

A.04 - Heal

Heal routines are fired whenever a player is healed from being satiated. The event value affects how much health is restored, and is manipulable like the Spawn and Damage event. The Target is the only valid entity in this event. Resulting values less than or equal to 0 cancel the event.

A.05 - ProjectileHit

This event is self explanatory. The event value is manipulable, like the Spawn and Damage event. Resulting values less than or equal to 0 cancel the event. Valid entities for this event are Projectile and Target, which refers to the entity that was hit (if it's alive).

A.06 - Spawn

Spawn routines are fired when a living creature spawns - animals, mobs, or humans. This event value is manipulable, and resulting values of 0 or less will cancel the event. The only entity in this event is the Target.

A.07 - Tame

Tame routines are fired whenever a Wolf or Ocelot gets tamed. Set the event value to a nonpositive integer to cancel it.

A.08 - PickUpExp

This is fired whenever a player picks up experience orbs. Set to 0 to gain 0 exp from any orb.

A.09 - PrepareEnchant

This happens when a player places an item into the enchantment table. {Bonus} is the number of bookshelves nearby, and {level_1} , {level_2} , {level_3} are the numbers that will be displayed in each slot of the enchantment GUI. Please beware that this event is sent multiple times by Bukkit. It seems to be twice when the item is placed, and once when it is picked up, but be careful about relying on that behavior. Also note that MC will occasionally throw an exception if you set one of the levels above 50 and a player picks one of them.

A.10 - Enchant

This happens when the player chooses an enchantment from the enchantment table. Changing {level} will affect the number of levels subtracted from the player.

A.11 - Interact

This happens when a player left or right clicks and doesn't happen to hit an entity. If the player does hit an entity, then left clicks become the Damage event, and right clicks become the (not yet available) InteractEntity event.

A.12 - ItemHeld

Occurs upon changing slot selection in game, for example item slot 1 to slot 2.

A.13 - Command

Occurs when a custom defined command is executed [by a player ?or? console] and runs routines defined under that command in the config. Warning: Defining commands can Overwrite pre-existing commands!

SECTION B - "How do I tinker with these damage relationships?"

[B.01] - Calculations

Uses a value calculated from nested routines to do something. Keep in mind that event values are preserved, so if you need a static value you should use a Set routine at the beginning.

- 'targeteffect.explode': 'set.9001' #Don't actually do this.

All value-manipulating routines do NOT affect the event's value if they are nested under a Calculation routine.

[B.02] - Conditionals

The primary control branch in ModDamage. Use Conditionals to control whether or not the nested routines will execute. See the second tutorial for more information on Conditionals.

- 'if condition':
    - 'routine'
    - 'if another.condition':
        - 'another.routine'
- 'if_not firstcondition and secondcondition': #If_not inverts the entire conditional.
    - 'yet.another.routine'
- 'if condition_one or (condition_two or !condition_three)': #condition_two and condition_three are in parentheses, and act as a single condition in relation to condition_one. condition_three is inverted.
    - 'umpteenth.routine'

[B.03] - Switches

Similar to switches in Java, these are used for more refined control branching than simple conditionals. With Switches, cases are checked sequentially until either a match has been found, or there are no cases left to evaluate. Only one matched case's routines are executed.

- 'switch.something':
    - 'CaseOne': 'single.routine'
    
    - 'CaseTwo':
        - 'nested.routine'
    
    [...]

    - 'LastCase':
        - 'another.routine'
        - 'yet.another.routine'

Some switches uses aliases as cases - see below for more details.

[B.04] - Routines: Exhaustively Listed Here

###Routines by Category

General Usage

Event Value

Entity/Mob

Player - anything from the Entity section above also applies to this section.

World

Server

###Routines by Type

Base

Calculation

Conditionals and Switches

Section C: Topics in MD

There are a lot of things you can do with MD. Sometimes an index of routines simply isn't tasteful to wade through, so a rough list of features is called for.

Though ModDamage certainly isn't limited to the design stated here, it was coded with simple to moderate damage mechanics changes in mind. Most of its power comes through the use of Conditional routines, which can allow other routines to execute only in the corresponding circumstance. Many might find the following snippet, for example, interesting if they are looking for alternatives to the current Skeleton damage mechanics:

Damage:
    - 'if attacker.type.Skeleton': 'set.0'     # The actual arrow does no damage to you.

ProjectileHit:
    - 'if shooter.type.Skeleton':
        - 'projectileeffect.explode': 'set.10' # I believe this works. Creepers explode at set.25
                                               # So this gives skeletons area of effect and block damage 
                                               # AS LONG AS they miss.

Section D: Miscellaneous Config and FAQs

[D.01] - Miscellaneous Configuration

This briefly describes each of the single-property configurations in ModDamage.

  • "debugging" changes how verbose your console output when using ModDamage (primarily for loading/reloading information). There are three modes:

    • "verbose" provides much more information and takes up considerable more space than "normal", but is useful for determining the nature of potentially complicated problems like in parenthetical expressions or misunderstandings with Message configurations.

    • "normal" prints out each valid configuration node that is found upon load/reload. This is on by default, since new users that have not configured this will likely want to be able to see this input (i.e., they have an unrecognized node name)

    • "quiet" suppresses all but critical errors and warnings that ModDamage might be thrown. When you're sure you've got the configuration you want on your server, it's suggested you use this to stop spamming your console with information that you already know.

debugging: normal

  • "disable-deathmessages" overrides vanilla player death messages that were introduced since Minecraft 1.0. This is useful if you want to use Message routines to make custom death messages, or just don't like them (Koryu doesn't!).

  • Tagging

    • "interval-save" is the time, in seconds, between automatic saves of tags ingame.

    • "interval-clean" is the time, in seconds, between automatic cleanups of tags ingame. This prunes any entities that no longer exist from the tag cache.

Tagging:
    interval-save: 120
    interval-clean: 120

[D.02] - Frequently Asked Questions

See the Pages entry, under FAQs - it is strongly recommended you look at these.

Tutorials

Clone this wiki locally