Customization

The long-term goal of Hack/Mine is to be thoroughly customizable, such that users can create their own content and share it with the community. As of version 0.6.4, this is starting to become a reality, as users can create their own spells via Spellscript and create their own classes and skill-sets through a configuration file (hsmConfig.JSON) located in the <.minecraft>/spells/ directory. This information propagates over the network automatically, meaning each Hack/Mine server can offer its own unique RPG experience.

You'll definitely want to use a syntax-highlighted text editor like Sublime Text when customizing Hack/Mine. A Sublime package for Spellscript is also available here.

The JSON Data Format
To customize hsmConfig.JSON, you first need to understand the JSON data format. A .JSON file is simply a text file, except its text must be organized according to a certain set of rules. If you're a programmer, you can probably understand the precise definition given here, but otherwise, read on.

JSON has three basic textual components: values, objects, and arrays. A value is either a string of characters enclosed in quotation marks, a real number, an array, an object, true, false, or null. An array is simply a comma-separated list of values enclosed by square brackets. And finally, an object is a comma-separated list of pairs enclosed by curly braces, where a pair is simply a string and a value separated by a colon. That's it! Here's some example JSON data: {   "someNumber" : 34, "anotherNumber" : 21.4, "aString" : "yo dawg", "anArray" : [2, 3, 5.2, null, "hi!"] "anotherObject" : { "herp" : 0, "aderp": 1, "alerp" : 2 } "jsonIsSuperAmazing" : true, "jsonIsComplicated" : false }

Now you're ready to customize hsmConfig.JSON...

hsmConfig Layout
At the highest level, hsmConfig is an object with several expected objects within it, including "classes" and "spells". Every object within the "classes" object will be added to Hack/Mine as a selectable class, whereas every object within "spells" will be added to the set of all possible spells that classes may have assigned to them. A description of all possible pairs for objects contained by classes and spells is now given.

Note: "LString" and "Script" refer to a strings that, if beginning '@', will be used to retrieve a value from the user's selected language files, or a script from the spells directory, respectively. Also, "Number" refers to any real number, whereas "Integer" refers to an integer. "Boolean" refers to values of either true or false. "Map" refers to an object. And finally, note that block and item IDs should be display IDs, which are consistent with the vanilla Minecraft IDs but differ from the ones you'd be using within Spellscript.

Class
To add a class to H/M, add a pair  :  to the classes object.  may consist of the following pairs:

Spell
To add a spell to H/M, add a pair  :  to the spells object. You'll also need to reference it from a class under the classes object via the "startingSpells" key (Additional methods of incorporating spells, such as in a talent tree, are planned.)  may consist of the following pairs:

Script Files
Script files can be placed in and referenced from the spells directory, and are interpreted as Spellscript scripts. For both "activeScript" and "effectScript", a return type of bool is expected, indicating whether the spell is successfully cast. The scripts also have the following variables in scope:

Custom Parameters
Custom parameters are a way of making your script files easily configurable and reusable. Rather than hard-coding particular values into your script files (for example, the strength of a jump technique), you can insert identifiers surrounded by double exclamation marks in their place (for example, !!JUMP_STRENGTH!!). Then, whenever one of those scripts is referenced in hsmConfig, you would also define an object of custom parameters, like: "mySpell": { "effectScript": "@spell_jump.ss", "effectScriptParams": { "JUMP_STRENGTH": "3.2" } }

Now for the spell mySpell, !!JUMP_STRENGTH!! will be replaced by the string specified in hsmConfig! Pretty cool, eh?

Since it's simple string replacement, you can replace custom parameters with whatever snippets of code you desire. Suppose you wanted JUMP_STRENGTH to depend on strength in one spell, and dexterity in another-- you could do something like this: "mySpell": { "effectScript": "@spell_jump.ss", "effectScriptParams": { "JUMP_STRENGTH": "3 + caster.getStr * .02" } }, "anotherSpell": { "effectScript": "@spell_jump.ss", "effectScriptParams": { "JUMP_STRENGTH": "3 + caster.getDex * .02" } }

Don't get too crazy though-- you want to be able to glance at a custom parameter's name and value and know exactly what it does, and depending on variables defined in another file can detract from this.