Plugin Writer's Guide

Plugins are files that amend or enhance an application. Several Halo Modding Tools are extensible through the creation of plugins. This is where you can document their extensibility.

Eschaton

Title: The Plugin Writer's Guide

Author: Sparky

Start Date: Monday, June 21, 2010

End Date: Monday, June 28, 2010

Introduction

This guide will help you create your own Entity-style plugins for the modding tool called Eschaton. This guide is also available for download and in that format is best viewed with the open-source and free Smultron application available at http://sourceforge.net/projects/smultron/. Smultron is available for Mac OS 10.4 through 10.6.

Requirements

• Eschaton 0.8.1+
• HexEdit
• Calculator (in your Applications folder) in programmer mode

Getting Started

1. Create a new file with Smultron or your favorite programming text editor.

2. Paste the following code at the top:

<plugin class="name" author="Name of the person creating the plugin" version="version#" headersize="Main">

3. Fill in the text values with the 4-letter tag class for which this plugin will be made, your name, and a version number. You can leave the headersize attribute alone.

4. Add some blank new lines and then put a closing </plugin> on the new line at the very end of your file.

5. Save the file as the 4-letter tag class followed by ".ent" (ie., actv.ent). Put this file inside a new folder called "My Cool New Plugins" or whatever, and put that folder inside the Eschaton Plugins folder located inside the Eschaton application folder.

Congratulations, you now have made the plugin recognizable by Eschaton!

NOTE: Eschaton will recognize any changes in the plugin after reselecting the plugin under "Current Plugin:" at the top of the Meta Editor. (Switch to another plugin and back, or click on the tag name again. You can set your new plugin to a higher priority under Preferences.)

Getting Offsets and Coordinating Eschaton and HexEdit

WARNING: Do not change any of the map's values with Eschaton while HexEdit has the same map file open, or Eschaton will crash.

1. Open your map normally (not expanded) with Eschaton.

2. Go to the tag type this plugin will edit and choose the first tag inside. (If your tag type is not inside this map, find or create a map that includes this type of tag. If a plugin has not been made for this type of tag, or if you have other difficulties, read the Basics of Map Reading Tutorial for more information about how to find the appropriate offset.)

3. Under Meta Editor, click on the first item, which is probably going to be a Bitmask16 or Bitmask32.

4. Copy the Offset value at the right.

5. Open the same map with HexEdit.

6. In HexEdit, type cmd-J or go under Find > Go To Address..., then paste the offset as a Hex entry and click Go.

Now Eschaton and HexEdit are on the same page, so to speak.

You can now determine various offsets and their types. Feel free to experiment, or if you need help, ask us at MGM (http://forum.halodemomods.com/). See existing Entity plugins (these end in ".ent") in the Plugins folder for examples.

Glossary

Credits 

Conure pioneered many of the types and attributes in his plugin set, titled "Conure's plugin builder v0.9". He pushed for Altimit01 to support these types in Eschaton. However, given problems coding with the dreaded RealBasic program, Alt was only able to provide initial support, as we see in his commented code in PluginLibUniversal.refresh_as_Ent while adding support for the nameNode attribute, "//and because conure is a flaming piece of doodoo"... During the course of making his own plugin set, Sparky (that's me!) requested that Altimit add support for the 'helptag' attribute, and also a new attribute that would display units of measurement, 'meas'. Realizing that the project code was in fact open sauce, Spark took on the project of adding support and he and Altimit are currently working to make Eschaton 0.8.3 happen. (UPDATE: Eschaton 0.8.1a and 0.8.1.1 were released by Modzy which include Sparky's Eschaton Plugins.)

Glossary Key

• no support in Eschaton 0.8.1 and earlier
• supported in Eschaton 0.8.1.1+

Types

angle 

a UI for displaying degrees or radians (most likely radians) as an angle

AngleBounds 

groups of two angle values, ie. bounds from/bounds to; may include a UI

bitmask8 

flags, only a few values

bitmask16 

flags, medium number of values

bitmask32 

flags, large number of values

colorbyte 

a single color

colorRGB 

three colors: Red, Green, Blue

colorARGB 

four color values: Alpha (transparency), Red, Green, Blue

dependency 

external tag reference

double 

very large numbers, typically used with indexed model data

float 

decimals, fractions (percentages/radians), large numbers

floatBounds 

groups of two float values, ie. bounds from/bounds to; may include a UI

enum8 (id8) 

a few popup menu items

enum16 (id16) 

even more popup menu items

enum32 (id32) 

lots of popup menu items

index 

referenced chunks; (in enum values, 65535 = 'none selected'); include the 'reflexive' attribute

int8 / char 

non-decimal numbers between 0 and 255 (unsigned)

int16 / short 

non-decimal numbers between 0 and 65,535 (unsigned)

int32 / long 

non-decimal numbers between 0 and 4,294,967,295 (unsigned)

loneID 

Description from Altimit01: LoneId is like a dependency. A dependency has 4 chars for the tag class, a 32-bit integer that when modified by magic points to the tag name, 4 bytes of zero, and an unsigned 32-bit integer that is unique to the tag. A loneID is just that integer. It's the ID alone.

note 

related to 'textbox', display information to the modder (for now, use the 'helptag' attribute instead) -- see Sparky's Plugins for an update to this

RealP3d 

a UI for displaying offsets

struct (reflexive) 

chunks/groups of data with similar structures

string4 

single line(s) of text up to 4 characters (typically used with tag names)

string32 

single line(s) of text up to 32 characters (typically used with single lines of text)

string128 

single line(s) of text up to 128 characters (typically used with blocks of text)

textbox 

displayed section header for purposes of information organization (for now, use a decimal 'section.subsection' hierarchy, ie. Unit.Flags, instead)

Common Attributes

name="name of item" 

displayed name of the item

name_offset="0x#" 

used with <struct>

offset="0x#" 

specifies the offset to the location of the tag data in hex code

visible="true/false"  

whether the item shows up normally or is 'hidden'; see Eschaton's Preferences

helptag="If set, this radius is used to determine if the object is visible." 

help text explaining usage

meas="world units" 

unit of measurement; ie. world units, seconds, radians...

nameNode="+/- #" 

unknown usage

info="Hi, this is my text help info for this item!" 

unknown usage, use 'helptag' instead

reflexive="main:magazines" 

used with index types to refer to the chunk location

Sample Entity Tags

<plugin class="name" author="Name of the person creating the plugin" version="version#" headersize="Main">

<bitmask32 name="name" offset="0x#" visible="true/false" helptag="">
	<option name="name" value="value"/>
	<option name="name" value="value"/>
	<option name="name" value="value"/>
</bitmask32>

<enum16 name="name" offset="0x#" visible="true/false" helptag="">
	<option name="name" value="#"/>
	<option name="name" value="#"/>
	<option name="name" value="#"/>
</enum16>

<float name="name" offset="0x#" visible="true/false" helptag=""/>

<string32 name="name" offset="0x#" visible="true/false" helptag=""/>

<struct name="name" offset="0x#" visible="true/false" size="#" helptag="">
</struct>

<dependency name="name" offset="0x#" visible="true/false" helptag=""/>

<short name="name" offset="0x#" visible="true/false" helptag=""/>

<colorRGB name="name" offset="0x#" visible="true/false" helptag=""/>

<note info="this plugin was automatically generated and may have some information that is wrong. Types that are not trustable: enums, and data"/>

<textbox title="---ITEM---"/>

<textbox title="message index">
	<line text="This sets which string from the tags\ui\hud\hud_item_messages.unicode_string_list to display"/>
</textbox>

</plugin>