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

Tutorial 1: The Basics of MD

Jump to bottom
Erich Gubler edited this page Apr 8, 2014 · 21 revisions

Introduction

Welcome to the ModDamage tutorial! If you're looking to start messing with almost all the mechanics in Minecraft, you've come to the right place!

This tutorial is intended to be an interactive, hands-on experience. If you don't already have ModDamage downloaded and placed in your Bukkit plugins folder, it's recommended you do so now.

Got that all done? Okay. Here goes.

ModDamage, by itself, does nothing upon installation. You may have noticed this if you just dropped the ModDamage JAR into your server plugins folder without a configuration...and nothing happened. This is because ModDamage configuration doesn't have any routines defined in its configuration (which, if this is a fresh installation, should have generated automagically for you)! Without routines, ModDamage literally will not do anything - it's up to you to put everything you want into ModDamage. ModDamage will never do anything you do not explicitly tell it to. Thus, our first question for this tutorial is: "How do we configure ModDamage?"

Note: The sample configurations in this tutorial should be easily pastable into ModDamage, though in most cases you may have to adapt them to fit your setup. If you're wanting to tinker, you should ask for help in our irc channel #ModDamage on irc.esper.net but the best way is to have your config open and Minecraft running so you can test your changes immediately.

The Tutorial

Routines: MD's Configuration Basics

Base Routines

To begin, we present the concept of routines. A routine is merely a single "action" that ModDamage recognizes Routines are the units of MD "code", or the most basic instructions for what you can get MD to do. Since the most effective way to help you understand what they are is through example, we shall be very liberal with demonstration of routines through example configurations, hereafter called "scripts". All routines, in order to be used, have to be put into an event, which from this point onward we shall call a node. The distinction between these terms will be obvious in a moment. Consider the following script in ModDamage:

on Damage  
    set.damage: 2  
    # set damage to 2. "damage" refers to the damage property of the Damage event.

    set.damage: damage+2 
    # add 2 to damage

    set.damage: damage-2 
    # subtract 2 from damage

    set.damage: 0  
    #set damage to 0

Let's analyze this script a bit. We're using a Damage node in the first line. A Damage node refers to whenever something in Minecraft gets hurt. All routines shown in this script execute every time a Damage event happens in Minecraft.
That said, we see that all of the routines start with the same thing. These are called Value Change Routines, and as they are they change the damage being dealt. They set the damage when the routine is executed. Numbers will ALWAYS set the value unless a sign is applied to the number, like in lines 3 and 4, which add and subtract 2 to the event value respectively. In the end, ALL damage events will have their damage set to 0, because the final line sets the event value to 0 regardless of what happened before.

At this point, try messing with your config a little bit. Try making all entities invincible (set.damage: 0), and then make everything a one-hit kill (set.damage: 9001). Make sure to test your config! Have no fear to experiment with the limits of your own creativity and the tools that ModDamage puts in your control.

At this point you may be thinking, "Come on, invincibility is neat, but there are several dozen plugins that can do that already!" Let's do something a bit more interesting:

on Spawn 
    if chance.50
        entity.explode.withfire: 40

Before we get into all the details, think about what this should do before you read on. This bit of script simply makes half of all the entities that spawn will explode with a little more power than a creeper, which would be 30. DO NOT TRY THIS CONFIG ON A SERVER YOU CARE ABOUT! It will wreck your worlds! On the other hand, you definitely should try it out, it's quite fun!

This slightly more complicated config uses our first Conditional - an expression that can be either true or false. There are many conditionals, one can check entity types, compare numbers, check if a player is sneaking, etc. In this case, we are using the chance conditional. When the event fires, every time MD finds a chance it will pick a random number between 0 and 100, and if the number it picks is less than the number after the chance, the conditional will be true. Or, in other words, every time the routine is encountered, there is a 50% chance that it will be true.

Now the conditional is in an if routine, which will simply run the routines that are inside (indented underneath) it only if the conditional is true. If the conditional fails, the routines will be ignored.

Also note that we aren't using the Damage node here - we're using the Spawn node. This node fires off whenever a living entity spawns in Minecraft. Inside the Spawn event the number that is modified is the spawned entity's health. Using value change routines like above will change the health the entity is spawned with. A value of 0 or less will cause the event to be canceled.

And finally, the most fun part, the Explode routine! The first part is a location where the explosion should be centered, and anything with a Location can be used here, including Entities and Blocks. The last bit, .withfire is optional. If it is present, the explosion will start fires the same way Ghast fireballs do.

Alright, lets look at some more conditionals.

Comparison

The Comparison conditional one of the most common and useful conditionals because we can also make decisions based upon certain properties of an entity in Minecraft. For instance:

on Damage # He who is stronger wins.
    if attacker_health > target_health   
        set.damage: target_health

Looks relatively easy to read, right? If the attacker's health is greater than the target health in any damage scenario, the damage is set to the target's health. When ModDamage expects a number, a user can replace that number with an entity property. We can also use parenthetical expressions like in programming, like so:

on Damage
    if (target_health - damage) <= 0 
        message.attacker: "&6You killed him, Jim."

Whenever it looks like the damage of the event will be a killing blow, the attacker is sent a confirming message, though this does not override Minecraft's death messages. There is a separate config option for that, located at the bottom of the config file.

There's a routine we haven't seen before. Messages simply send a chat message to one or more players. They can be colored, and can have other variables mixed in. If you want more details after the tutorial, make sure to check the wiki. Messages are also a useful debugging element in ModDamage. If you want to figure out why your routines don't seem to be acting when they should, putting a message routine is a good way to be absolutely sure that it's firing at the right time.

Consider the following configuration with a single Conditional routine:

on Damage #Only Admins survive...
    if attacker.type.Creeper
        set.damage: 200
        if target.group.Admin
            set.damage: 0

Summary: The damage dealt in any damage event involving an attacking Creeper will be 200, unless the target is a member of the group Admin, in which case damage will be set to 0. Therefore, only Admins could possibly survive MC's favorite suicidal shrubs with this configuration.

Retrospectively it's easy to see the use of the "attacker.type" conditional in Minecraft. The EntityType conditional is a crucial part of any reasonably complicated configuration, and those who are new to ModDamage should become acquainted with the ModDamage Elements hierarchy, an internal interpretative structure used by ModDamage. Unfortunately, at the moment the best place to find it is in the source code, but if you want to add it to the wiki, you should!

Here's another example of the Entity Type conditional put to use:

on Damage
    if attacker.type.human 
        set.damage: 4
        if attacker.group.Admins and target.group.Default: 
            set.damage: *2 
    if target.group.Default: 
        set.damage: +2 
    # Not affected by attacker.type conditional

The characteristics of this configuration can be readily summed up in English:

  1. All humans have a base attack damage of 4, regardless of the item in hand.
  2. Any member of the group Admins deals twice as much damage to any member of the group Default, which in this case is 8 (a hefty four hearts!).
  3. Any member of the group Default takes an additional 2 damage from all damage sources.

So, if a member of the group Admin were to attack a member of the group Default, then it would be calculated as (4 * 2 + 2) = 10. Likewise, if a member of any other group attacked a member of Default, the calculation would simply be (4 + 2) = 6 damage.

It's worth pointing out that while players will usually be the only ones affected by this configuration, NPCs, IronGolems, and Villagers will also consistently have their damage values set to 4, because they are also considered "human" entities. Use attacker.type.player to be completely specific, instead of the "parent" type of human.

With the introduction of control branching it is very important to note here that the order of operation for MD configuration is exactly in the order you place it. Top to bottom, and left to right.

One more example:

on Damage
    if attacker.group.RedTeam
        switch attacker.wielding
            Book
                targeteffect.heal: 2
                set.damage: 0 
                # Set the damage value to 0, since we're healing this guy. Negative results for damage events usually result in their getting cancelled.
            Bookshelf 
                if target.group.RedTeam 
                # Multigroup is awesome this way - only allow this to heal teammates.
                    targeteffect.heal: 6
                    0
            Coal
                if !target.group.RedTeam and target.isonfire
                    set.target_fireticks: +range(30, 100) 
                    # Sets the target on fire, though this is a fairly random number. :D

This configuration allows for RPG-type healing and, perhaps more importantly, lets players of the RedTeam group set people outside of that group on fire.

There are three new routines used in this config: the Change Property Routine used for fire ticks, Heal, and the Switch routine.

Hopefully by this point you have a gist of what ModDamage syntax is like, and should be able to write a bit yourself. There are dozens of major features that are yet to be explored, but these are outside of the scope of a basic understanding of routines.

Wrapping It All Up: Testing Your Configuration

With any feature on a server, it's a good idea to test thoroughly so you don't have any surprises. Refer to this FAQ page to learn how to debug your configurations in MD!

That's about all there is to basic ModDamage usage. Pat yourself on the back! You finished the first tutorial! With these basics alone, you should be able to configure ModDamage to suit some common needs. If you're looking to get tap into the more powerful features of MD, check out the next tutorial.

Tutorials

Clone this wiki locally