Note: This is the latest, and hopefully last, revision.

Note: Due to the fact that the PHPBB extension for creating "Pages" such as this one strips off leading white space on a line some sections will appear in the format usually used for program code for readability and general appearance because that preserves leading white space.

eScript Style and Distro submission Guide
This is a suggested guide for those writing eScript programs and a required guide for on the Distro team or for those wishing to submit eScript programs or packages to the Distro. I want to thank Austin for creating the original style guide. I'm pretty sure it was his handy work. If not then my thanks to whomever created it. I changes a few things but most of this guide was taken from the original.

Naming Conventions:

The letter of the first word is lowercase, while the first letter of each additional
word is capitalized. This naming convention is known as camelCase. All file extensions
are lowercase.

CODE: Select all


        Commands are all lowercase.
        Core files, such as itemdesc.cfg, serverspecopt.cfg,npcdesc.cfg, etc.,  are all lowercase.

CODE: Select all

        var my_integer;
        var my_string;
        var layer_array;

        Constant variables are all capitalized and words are separated
        using the underscore character '_'.

        CONST MY_CONSTANT := 10.0;
        CONST NUMBER_OF_GUARDS := 100;

        object.someproperty := 100;
All functions use the PascalCase convention, which as you can see has the first
letter of each word capitalized.

CODE: Select all

        function ListOnlineDrow(who)
        function GetLastName(who, num_of_letters)

        If the function/s is part of a special package it can include a small
        prefix to define its origin i.e. AI_GetNerves(mobile).

All programs are named after the file in which they are contained. Unlike their filenames
though, they can either follow the 'camelCase' or 'PascalCase' naming conventions.

CODE: Select all

        (FileName is "bardInstruments.src"), thus the program is named:
        program bardInstruments(item)

        (FileName is "enumerateTowns.src), thus the program is named:
        program EnumerateTowns(who, uX, uY, lX, lY, realm)

        There are certain exceptions with special kind of programs, such as commands
        i.e. command_MyCommand(who, params) or textcmd_
        or a spell program
        i.e. spell_GreaterHeal(who)
=== Other Formatting ===


CODE: Select all

// BAD
// Proper
        return 0;
        return <some_value>;

CODE: Select all

        var math := 4 + 3 * 10; // 70 or 34? Use parethesis to control better.
        var pemdas := ( ( 4 * 4 ) + ( 8 / ( 3 + 2 ) ) ) - ( 100 + some_var );
Please note that I prefer no spaces between parenthesis and values or parenthesis and another parenthesis however a case could be made for readability when having the spaces present. So we won't have a hard and fast rule regarding this. However spacing between values and operators is strongly encouraged.
Either of the following will be acceptable:

CODE: Select all

        var pemdas := ((4 * 4) + (8 / (3 + 2))) - (100 + some_var);
        var pemdas := ( ( 4 * 4 ) + ( 8 / ( 3 + 2 ) ) ) - ( 100 + some_var );
// Strings have spaces around the + operator.

CODE: Select all

        var string := "Hello there " + "Stephen." + " I am " + math + " years old.";
Function Usage:
var value := SomeFunction(argument_1, argument_2);
var other_value := object.SomeMethodFunction(argument_1);

object.somepropery := some_value;


CODE: Select all

// Do unto others as you would have them do unto you.

 * This is another option
 * When creating multi line comments.

A word about comments in your code, you can never have too many comments documenting what your code is doing but you can certainly have too few.

Whenever possible you should provide a comment block preceeding a function like the example below, especially if this function is one that might be used by others.

Taken from Austin's file:

CODE: Select all

 * ApplySpellDamageEX(mobile, amount, type, source, circle)
 * Purpose: Does spell damage to mobile taking into account mobile's AR
 * Parameters
 * mobile: Victim
 * amount: Raw damage
 * type:   Fire, cold, energy, poison or physical
 * source: Source of the damage
 * circle: Circle or level of spell. Basic spells are 1 through 8.
 * Return value: damage amount done
If, While, etc. Stuff:
Please take note of the indentation inside the conditional satements (if and case) and the loops (while, do, repeat, and for etc.). This is important for readability so others can look at your code and understand it. You should always indent 4 spaces inside each if or loop.

CODE: Select all

        if ( something )
                Code here;
        if ( this || that ) // Dont use 'or' spelled out.
        if ( this && that ) // Dont use 'and' spelled out.
        if ( this || ( one && two ) ) // Parenthesis are important for order of operations.

                do this stuff....

                this gets done...
                if(this happens)
                        this other stuff gets done
                        do this stuff

        case ( something )
                value:    code;
                default:  code;

        while ( something )
                code here;

        dowhile ( case );
        foreach iteration in ( iterated )

        for ( i; i <= 4; i:=i+1 )

        for i:=1 to value

CODE: Select all

// Dont make arrays like this
        var a := {1, 2, 3};
        var b := {};
// Proper way
        var a := array{1, 2, 3};
// Either below is acceptable
        var b := array{}; 
        var b := array;
// Struct setup
        var my_var := struct;
        my_var.+member := something;
// Or...
        var my_var := struct{"member":=something, "member2"};
// Dictionary Setup
        var my_var := dictionary{"key"->value, "key2"->value};
Other Notes:
* Do not use spaces for indents, use tabs. I would prefer tabs = 4 space characters but 2 space sized tabs is acceptable.
* All Distro scripts that use gumps, can use the gumps package to build them.
* Gumps should be made for a 640x480 screen.

Additional Distro submission guidelines:

Follow as closely as possible the eScript guidelines for coding.

General use include files (*.inc) can be placed in \scripts\include. Examples are, etc.
All specialised include files specific to a package shall be included in the package that requires them.

Going forward, packages should be as self-contained as possible. This means that if at all humanly possible
a package should be able to be dropped in without modifying any other packages or scripts outside the
package. This is especially important if you are submitting an optional package that shard devs can, should they
choose, add to their server. If you need to add or modify some function in an existing Distro include then
copy that include to your package and modify it there. This will help keep the Distro as simple as possible.

Packages will follow the "Austin" format:
<main scripts go here> start.src, logon.src, reconnect.src etc.

<cfg files> itemdesc.cfg, icp.cfg, npcdesc.cfg (for any custom NPCs your package may need) etc.

< files specific to this package>

<method and use scripts required for an item> Create additional itemname directories for additional items as required. The use script for an item should be named use.src and the method script should be namedmethods.src

Also familiarize yourself with the control package in \pkg\utils\control and create an icp.cfg file for your
package. Try to be as thorough as possible when adding the info to the icp file.

We don't yet have a system set-up to submit candidate packages for the Distro or optional add-on packages.
Hopefully, we can get that done and make it available. You can submit patches to the Distro through Git.

*** Insert small tutorial here for submitting patches through GitHub ***
*** Someone other than me will write this tutorial or be assigned it ***