D2BS

Seeing as I don't want a repeat of the craziness that is the 1.x API, here's some ground rules:

1. All API functions must have a real C function backing them. API functions should do no more than validate and convert arguments, then pass them on to some sort of real function that does the work behind the scenes.
2. Create objects sparingly. Don't create an object just because your function got called--update an existing one where possible. Share objects between scripts wherever possible.
   • The only objects that currently aren't shareable between threads right now are arrays, due to a spidermonkey bug. Mark any places where you would share an array, but build a new one instead, so that once that bug is fixed, the code can be changed.
3. All classes must implement a toString method (this is done with the JSClass.convert hook) that returns something reasonable for the string form of the object. Make sure the string form is appropriate (e.x. units return the unit's name, a file will return the file's relative path, etc.).
4. All functions must avoid the use of magic numbers wherever and whenever possible. Wrap magic numbers in an object instance and make that object be the required parameter. This leads to easier type checking internally, as you can just do JS_InstanceOf or JS_HasInstance to determine if the object is the right class.
   • For instance, setting a skill should require an instance of a Skill object, which can be retrieved via some array on a Unit. The function that sets a skill can check first if the parameter is a Skill object, and then if the Skill object belongs to the current player (via some internal property). If both of those conditions are met, then the skill can successfully be set without issues. This solves two problems: one, testing if a skill is settable; and two, telling what item id to use for the skill.
5. Only make a function global if there is absolutely nowhere else to put it. I'd like there to be only 4 primary global functions: load, include, sleep, and print. Print should actually be on the Game object, but the functionality of it leads it to being better placed globally.

More to come later. These rules subject to revision based on the results of the API Discussion.