3.2 JS API Wishlist :)

[aubergine]

enumArea() or enumRange() can be used to get objects at specific positions.

I dunno, I just feel that in practice derrickPositions[] doesn't seem much use -- because you still have to work out whether the position is a derrick or an oil resource. Also, I find the array name very confusing -- it gives the impression that it's either a) where derricks are or b) where you could build derricks, when really it's telling you where oil resources are and those resources may or may not have derricks built on them. And, because it alludes to derricks, one would expect it to be updated each time a derrick is built or destroyed, but the array is static throughout the game. If it were renamed resourcePositions[] that would make more sense IMHO.

[aubergine]

Hrm, ok, been thinking more about derrickPositions[] -- Per is indeed right (as always!) that it will be way quicker looking at that list than doing enumFeatue() and enumStruct(). Maybe a enumTile(x,y) to return an array of objects on that tile (just in case there are multiple objects, empty array if no objects) would make derrickPositions[] a much more interesting proposition.

[Per]

I am thinking of adding a getObjectAtTile(x,y) function, which will return any structure or feature at the given tile, but not any droids. The reason for this is that we cache knowledge of features and structures at tile positions, while we'd have to iterate the droid lists to get any droids on the tile, so excluding droids would make it far faster. And it would guarantee that only one object is returned.

[aubergine]

Sounds good, but maybe with less ambiguous function name? Uhm.... getStaticAtTile() urg. getBlockingObjectAtTile() ick, too long. getObstacleAtTile() ...?

[Goth Zagog-Thou]

Happy to see makeTemplate() added. That'll simplify things for me quite a lot.

[aubergine]

Shorter name for feature/structure at tile function: getObstacleAt(x,y), + also additional syntax: getObstacleAt(positionObj)

eventArea<label>(droid, label, filter) -- new label and filter params

With dynamic area labels being an obvious direction for modders, it will be useful to have the label and filter passed in to the event handler.

This will make it much easier to clear down functions and variables, etc., after an area event fires -- while there are various alternate approaches which can also be used (see Wrecks for an example), they all require creation of new functions for the event handler, which is not overly performant when heavily utilised. By having the label passed in to the event, a static function (which will be more heavily optimised by the JS compiler than a dynamically created function) can be used for multiple area events.

Code: Select all

var reusableAreaListener = function(droid, labelName) {
   var area = label(labelName); // I *really* wish label() was called getLabel()!
   var wreck = getObstacleAt(area.x, area.y);

   // obviously do some checking to make sure it's a wreck (omitted for brevity)

   // give droid.player whatever it is they get for collecting wreck (omitted for brevity)

   removeObject(wreck); // remove wreck from map
   removeLabel(labelName); // clear down AREA object & label
   delete this["eventArea"+labelName]; // delete listener function
}

function eventDestroyed(victim) {
   if (victim.type == DROID) {
      addFeature(....); // create wreck
      addLabel(....); // register labelled AREA object
      this[eventArea+labelName] = reusableAreaListener;
   }
}

And, having the filter passed in will make it easier to have re-usable functions that resetArea() when triggered.

Rename label() to getLabel(), remove label() function

Every time I type label() I cringe. For consistency with everything else in JS API, could it be renamed to getLabel(), with the old label() function being completely removed, not just deprecated, in the process?

3.1 scripts are likely not using label() function anyway -- and it's trivial to make a backwards-compatible script should it be required:

Code: Select all

// create getLabel alias on wz 3.1
if (typeof getLabel == "undefined") this.getLabel = label;

[aubergine]

Happy to see makeTemplate() added. That'll simplify things for me quite a lot.

<edited>

Yup, we're starting to get access to more stats

Would be also useful if we had some way to addTemplate() or saveTemplate() -- those functions would be useful prep work for future GUI overhaul as well.

[Per]

Shorter name for feature/structure at tile function: getObstacleAt(x,y), + also additional syntax: getObstacleAt(positionObj)

A feature is not necessarily blocking...

Rename label() to getLabel(), remove label() function

Every time I type label() I cringe. For consistency with everything else in JS API, could it be renamed to getLabel()

Yes, I caught myself using 'label' as a variable names a few times already... But there is already a getLabel() function. Perhaps objectFromLabel(label) instead?

[aubergine]

What about making getLabel() fulfil both needs? So if the parameter is a string, it returns object associated with that label, if the parameter is an object, it returns the label associated with it?

[Shadow Wolf TJC]

Deprecate derrickPositions[] array -- it can't be relied on, and it's confusing:

* it's listing locations or oil resources (with or without derricks built on them), not locations of derricks = confusion
* it doesn't take map-placed derricks, or the effects that baseType setting has on those derricks, in to account
* It doesn't get updated during the game

As a result, we all use enumFeature() to find oil resources, and enumStruct() to find derricks, so there's little point in having the derrickPositions[] array IMHO.

enumArea() or enumRange() can be used to get objects at specific positions.

I dunno, I just feel that in practice derrickPositions[] doesn't seem much use -- because you still have to work out whether the position is a derrick or an oil resource. Also, I find the array name very confusing -- it gives the impression that it's either a) where derricks are or b) where you could build derricks, when really it's telling you where oil resources are and those resources may or may not have derricks built on them. And, because it alludes to derricks, one would expect it to be updated each time a derrick is built or destroyed, but the array is static throughout the game. If it were renamed resourcePositions[] that would make more sense IMHO.

Perhaps we should indeed have a resourcePositions[] array that lists all oil resource points on the map, regardless of whether or not they have derricks already built on them at game startup, though perhaps we should also add a .player property to the position objects that this array would return, in order for AIs to be able to tell which player would claim this resource on advanced base settings, or if Scavengers are enabled.

[aubergine]

I thought features were blocking, until you destroy them heh. In any case, obstacle to me seems the best word as it's a thing on the map that you'd either have to go round or blow up if it was in your path.

Why not just make resourcePositions[] be a list of game objects, that gets updated whenever a RESOURCE_EXTRACTOR is constructed/destroyed?

And now that its a list of game objects, simplify the array name to just 'resources[]'...

Code: Select all

resources.forEach( function examine(resource) {
  if ( resource.stattype == OIL_RESOURCE ) { // .stattype on resource objects feels wrong btw
    // free oil res, consider capturing it ('resource' = feature object)
  } else if ( !allianceExistsBetween(me, resource.player) ) {
    // enemy derrick, consider attacking it ('resource' = structure object)
  }
} );

If this approach is taken, I think it would be a good time to deprecate .stattype and .droidType in favour of a new .subType property that's common to all game objects. The .stattype and .droidType could be retained for a few versions to ease transition to .subType.

Not only is .subType a more descriptive property name, but the fact that now all structures, droids and features would have a .subType means that we are no longer forced to always check .type before investigating the sub type.

[aubergine]

Tweaks to structures / features

On structure objects, I'd like to see .status extended to include:

* BLUEPRINT -- construction has not yet started (such objects might only be available via a new enumBlueprints() function?)
* BEING_DEMOLISHED -- we currently have no decent way to know when a structure is being demolished

BLUEPRINT and enumBlueprints() will be useful when I have an idle truck - I can quickly find a blueprint for it to help construct, and, in particular, actually order it to HELP_BUILD without having to wait for construction to start.

BEING_DEMOLISHED was removed in 3.1 branch because the game engine didn't actually use it. My understanding is that only the trucks knew whether they were constructing or demolishing. I was wondering if we could add the necessary code so that a structure will know what's happening to it, and then reintroduce this constant. The current approach of BEING_BUILT for both construction *and* destruction is icky, because it means scripters have to keep their own records of what trucks are ordered to do, and those lists can get out of synch for a variety of reasons (not to mention they add lots of cruft to the script).

Also, is there any way we can work out if an oil resource is burning? Maybe the .health of an oil resource can be used as an indicator of how long it has left to burn? Where 100 - feature.health == time until burning stops. (So .health == 100 means it's not burning). Alternatively, just have health == 0 to indicate it's burning, which has added advantage of being a falsey value.

[Shadow Wolf TJC]

Perhaps there could be a new droid order, DORDER_ASSIST, that can be given to trucks through orderDroidObj() to have them follow another truck around and help it build whatever it's assigned to build?

[aubergine]

Nice idea! But maybe instead re-use DORDER_HELP_BUILD? So you could either use that constant on a structure to help with just that structure, or another truck to follow whatever that truck does.

And, on a similar note, being able to tell VTOLs to support a transport would be nice.

[aubergine]

eventUncaughtException(error, msg[, include])

An event that triggers when an uncaught exception is received by the JS environment. If eventUncaughtException() itself throws an error, that error will be ignored to avoid recursive loops of dooom.

Parameters:

* error -- the JS error object that was thrown
* msg -- the string that the JS API intends to put in the log file
* include -- only defined if the error occurred during an include(), will be the file path that was being included at the time

This event handler will allow me to automatically load diagnostic and unit test scripts when an error occurs, and thus dump() detailed script state information to help track down the problem. Uses experiencing errors can then provide the game log and script log files and I should have everything I need to track down the bug.