Javascript API documentation

[aubergine]

Javascript isn't typed per se, but you can determine if something is based on a specific functional class using the 'instanceof' binary operator (which really just checks through the prototype chain but should be enough).

I'm not sure I want to add notes to game objects, I'd rather be able to store game object id's and then get the object back later if needed. What specific benefit would storing props on game objects provide?

[aubergine]

Except eventStartLevel() is not called on game load... If need be, I can add an eventGameLoaded().

There is already eventGameInit() - how would eventGameLoaded() differ from that? And in any case, it seems that eventStartLevel() is the most popular place currently to initialise stuff.

Groups. I intend to change their implementation to be more general (allowing droids to be member of multiple groups, eg), but they are already a good way to store droid information persistently. They are saved and loaded. Whenever a droid is destroyed, it is immediately removed from the group.

Uhm, not overly keen on that approach. Personally I'd prefer it if groups were nice and simple where a droid can only be in one group at a time. I will often be setting commands for all droids in a group, and so if a droid is in more than one group it's going to get conflicting commands.

I want to add a new persistent structure that I have called 'annotations' so far. Basically they are custom fields added to any game object, and that are added under a .notes object attached to them when you get them from the scripting API. Eg you could call "annotate(oil, "hqSentToBuild", gameTime);" to add a oil.notes.hqSentToBuild property that contains the gameTime that you last sent a droid to build on that oil resource. (I think it is is a good idea to add them under a .notes hierarchy to avoid future name collisions.)

Maybe I don't understand the "snapshot" nature of game objects - I would have assumed that there would be properties of the JS object that "behind the scenes" call getters/setters in WZ whenever they are called? That being the case, during gameplay (ignoring save game persistence issues for now) surely I could just add a property to the game object, eg. someDroid.foo = {...}?

You cannot not use the above to store one game object in another, though. Eg you could store the attack target of a droid, but that would only give you the snapshot information of that object when you added it, so querying that information later would be next to useless.

I would tend to store droids, etc. by their IDs anyway, then I can always get latest data using .objectFromId().

[Per]

There is already eventGameInit() - how would eventGameLoaded() differ from that?

eventGameInit() is run much earlier in the loading process. It is nearly always better to use eventStartLevel(), though. Both these only run when game is first started, and neither is run when it is loaded.

Maybe I don't understand the "snapshot" nature of game objects - I would have assumed that there would be properties of the JS object that "behind the scenes" call getters/setters in WZ whenever they are called?

No, they don't.

surely I could just add a property to the game object, eg. someDroid.foo = {...}?

You can, and I've used that to some effect already, but the moment your copy of the game object goes out of scope, then that property is gone.

[milo christiansen]

Maybe I don't understand the "snapshot" nature of game objects - I would have assumed that there would be properties of the JS object that "behind the scenes" call getters/setters in WZ whenever they are called?

No, they don't.

Why not if I may ask?

[aubergine]

... Both these only run when game is first started, and neither is run when it is loaded.

Oh, in that case yes - we do need that extra event otherwise we can't do stuff on savegame load.

Maybe I don't understand the "snapshot" nature of game objects - I would have assumed that there would be properties of the JS object that "behind the scenes" call getters/setters in WZ whenever they are called?

No, they don't.

[/quote]

So, if I've got this straight, something like this is happening...

In C++ land:

Code: Select all

create an array
loop through each matching droid {
   create an object
   for each property of a droid {
      object[property] = droid[property] // this will be calling getter func on each property, in addition to making a copy of the value!
   }
}
expose array to javascript


So you're basically doubling the RAM usage of the entire list as you've just made a clone of it for maybe a single function in JS to use. And because people are in the habit of using enum<Whatever>() each time they need a list (because old list will likely be out of date = people won't bother caching it in JS), you're going to be doing that over and over and over again?

Look, would it be better to take a different approach like this:

Code: Select all

create an array
loop through each matching droid {
   push droid.id on to array
}
expose array to javascript via a wrapper/helper function


In C++ land you'd have two functions (or maybe several) that would facilitate getting/setting of properties as applicable. The wrapper/helper in JS land would then interface with the C++ getter/setter functions as applicable. Using inheritance and proper properties (eg. defined using Object.setProperty) you'd get a beautiful environment JS side. Examples:

* console(typeof someDroidObj) // DroidObject
* (someDroidObj instanceof BaseObject) // true
* someDroidObj.isVTOL() // calls isVTOL(someDroidObj)

Thanks to inheritance the instantiation of objects has practically zero overhead, regardless of number of properties due to prototype chain inheritance. And, because property values are only accessed on an as-needed basis, that gives performance and RAM-consumption benefits too. Furthermore, because the JS properties will be calling the exposed C++ getter/setter functions directly, there's practically zero extra overhead in the overall chain from requesting a property value to returning it compared to the current approach being used (and the current approach is doing all that work for every property of every item regardless of whether it will be used or not).

And, finally, and this is the big one IMHO, the object properties in JS will always get the latest values when accessed - so all this stuff can be cached in JS land. Obviously a simple check would need to be made to ensure the droid/struct/feature still exists, but that is fairly trivial to implement on the JS side (or simply catch exceptions in JS if an error is thrown in C++).

This could go even further, the lists (of ids) themselves could be made fully dynamic too! So when you iterate through a list, it already knows what "filters" the list should have, the JS list wrapper asks C++ for a new list with those filters and as far as the JS developer is concerned the list is always up-to-date and the objects in it are also always up-to-date! I can write a custom Array class (that for all intents and purposes is *identical* to a normal JS Array) which would transparently handle the calls to C++ functions, etc.

With my OOP inheritance stuff, I could then easily create subsequent classes which are more specialised (eg. droidList, structureList, featureList, etc).

Oh, and dare I mention that all these things could then be much more easily persisted - for example, uneval(someList), someList.toSource() or someList.valueOf() (which is what I assume your persistence layer does on global vars during savegame) would be returning a simple array of primitive numbers = nothing breaks in save/load cycle!

I really think there's a massive opportunity here to radically improve the scripting engine from script-developer perspective, and such a radical change would be better to do sooner rather than later. What's more, the existing JS API can be retained - we'd simply be adding some new global functions to it to allow the next-generation approach. I'm more than willing (in fact, practically begging!) to write the JS wrapper/helpers. Please give it consideration - it would be astonishing API with this sort of stuff.

surely I could just add a property to the game object, eg. someDroid.foo = {...}?

You can, and I've used that to some effect already, but the moment your copy of the game object goes out of scope, then that property is gone.

My wrapper/helper function idea above would completely solve that issue IMHO.

[aubergine]

Also, out of interest, do you know what JS version (or ECMA-262 Edition) is used in WZ? (or what JS engine, eg. SpiderMonkey, Rhino, etc)

From my current dabbling it seems like Rhino or SpiderMonkey - eg. __proto__ exposed to JS scripts (which is awesome!)

[aubergine]

Here's another concept to ponder.

Imagine for a moment that the JS script is running in a web browser. (humour me, this will make sense shortly...)

There's a bunch of stuff available from the JS engine: Object, Number, Array, etc.

There's a bunch of stuff available from the browser (in our case: WZ): Map, Players, ObjectList, etc.

Then there's the web designers scripts (in our case: AIs, campaigns, etc.): custom scripts & stuff

What I'm really interested in getting right is the stuff made available from the "browser" (WZ). I truly believe that WZ should behave a bit like a DOM. I'm willing to commit *lots* of time to this - not just coding (JS only - can't help with C++ sorry), but documentation too, and unit testing if needs be (although never done that before so wold need some help there).

Some examples:

wz.players // an array of PlayerData objects
wz.map.continents // an array of continent objects
wz.map.structures // an array of structures
wz.map.features // array of features on map
wz.map.tiles ... etc ...
wz.limits // object (hash map) of applied limits
... etc ...

Some things could be accessed (or filtered) in different ways, eg:

wz.map.structures // by default all structures for all players
wz.players[0].structures // just structures for that player
wz.players[1].structures.visibleTo(me) // player 1 structures that player <me> can see

In reality, all these things are just wrappers/helpers to a relatively small set of C++ functions. Take those 3 structure examples above - we already have a function for that, so literally no extra coding needed on the C++ side.

So, really, if you'd consider it, I could spend some time coming up with a proposed specification for this WZ DOM, working out what sort of functions would be needed on the C++ side of things and submit it for review?

[NoQ]

Also, out of interest, do you know what JS version (or ECMA-262 Edition) is used in WZ? (or what JS engine, eg. SpiderMonkey, Rhino, etc)

QtScript, i guess ...
Well, that's a nice reason for using Qt, even if it's not used for rendering (networking is another good reason (?))

[aubergine]

And there's more...!

Once we have a WZ DOM, we can then do some seemingly crazy (but actually quite marvellous) things like port jQuery to WZ!

This would mean that AI/Campaign/etc script devs could use jQuery-like selectors to do stuff.

For example:

Code: Select all

$("players.3 trucks:nearest").attackWith(someDroid);


Very basic example, but you get the point. Just as you can "select stuff, do stuff with it" in a browser using jQuery, the adapted wzQuery would allow you to "select stuff, do stuff with it" in Warzone.

And while it might seem like it's a big and crufty way to do things, it will enable really fast prototyping of AIs, etc., then any slow bits can use more normal methods to get better performance.

Remember also that I've been developing a "FrameThread()" class which allows any "do stuff" tasks to be run non-blocking across multiple frames to avoid stuttering for end-users.

[aubergine]

Found a really nice summary of qtscript here for future ref: http://doc.trolltech.com/4.3/qtscript.html

They never seem to state which edition of ECMA-262 they are supporting, but from what I can see most of the good stuff is in there (see list of tasty stuff at bottom of page). From that docu, it's also clear that objects in JS land can be properly connected to objects in C++ land - eg. getting a property of a droid in JS calls relevant method of that droid in C++ thus giving latest value.

And, more importantly from my perspective, all the qtobjects in JS land are using proper prototype chains that end at Object. This means I can do lots of good stuff with them!

[Rman Virgil]

Also, out of interest, do you know what JS version (or ECMA-262 Edition) is used in WZ? (or what JS engine, eg. SpiderMonkey, Rhino, etc)

QtScript, i guess ...

Well, that's a nice reason for using Qt, even if it's not used for rendering (networking is another good reason (?))

QtGui Module another good reason... or not ?

- RV

.

[Emdek]

I suggest to use latest documentation, not ancient one.
http://developer.qt.nokia.com/doc/qt-4.8/qtscript.html

QtGui Module another good reason... or not ?

It would require very big UI rewriting, but it is needed anyway I guess.
And the best way would be to use QGraphicsView or even QtQuick / QML (using components instead of QWidgets) but I have no idea if they could be painted painlessly on OpenGL scene...
Also it is better idea to reevaluate this when Qt 5.0 will be released (probably around June).
But such as things should be probably discussed in separate thread.

[Rman Virgil]

I suggest to use latest documentation, not ancient one.
http://developer.qt.nokia.com/doc/qt-4.8/qtscript.html

QtGui Module another good reason... or not ?

It would require very big UI rewriting, but it is needed anyway I guess.
And the best way would be to use QGraphicsView or even QtQuick / QML (using components instead of QWidgets) but I have no idea if they could be painted painlessly on OpenGL scene... Also it is better idea to reevaluate this when Qt 5.0 will be released (probably around June).

Appreciate your insights and knowledgeable suggestions, Emdek.

But such as things should be probably discussed in separate thread.

Your right. Should be separate thread discussion (though new UI & new A.I. changes are joined at the hip in my minds eye - now how's that for an oddly mixed metaphor ).

- RV
.

[aubergine]

The big issue I have with the latest qt online docs is that it's predominantly written from the C++ perspective, and not the JS scriptwriter perspective.

For example, is there something I can use in my JS that is similar to defineProperty ?

If I can define proper properties and their flags in my JS that will make my code so much better. But reading the nokia docu site it's very difficult for me to understand what bits of ECMA-262 (or even which edition) and any non-standard extensions are available to me as a JS dev.

I can sort of make out that from the C++ site (I find C++ code really confusing to read) the property flags and stuff like that are all available, but I can't work out if there's some way I can access that stuff from my JS.

EDIT: Finally found a link to this: http://developer.qt.nokia.com/doc/qt-4. ... cript.html <-- that's the sort of stuff useful to a JS dev.

[Emdek]

Well, that's normal, in this case scripting is an addon to C++.
As far as I know this module currently uses JavaScriptCore as backend so best way is to find its documentation.
And best way to check if something is available is to try using it and checking if it throws an error.
Sadly there is no easy to use interpreter with GUI in examples section:
http://developer.qt.nokia.com/doc/qt-4. ... cript.html
But it is extremely easy to create one.