3.2 JS API Wishlist :)

[Shadow Wolf TJC]

A few little ideas that just popped into my head:

setSkyBox()

Basically, this would change the skybox of the map to whatever skybox is specified by the function. It would only have 1 mandatory parameter, namely, the directory of the texture you'd like to use as the skybox. (For example, you'd input "texpages\page-25-sky-urban.png" if you'd like to use the urban skybox for a certain Arizona map.)

setWeather()

This sets the weather throughout the entire map depending on what the 1st (and only) parameter is, which could be WEATHER_CLEAR for clear skies, WEATHER_RAIN for rain, or WEATHER_SNOW for snow. (Later on, additional weather effects could be added, like WEATHER_STORM for thunderstorms (complete with thunder sounds), WEATHER_SANDSTORM for sandstorms, or WEATHER_BLIZZARD for blizzards.)

setMapColor()

This applies a color filter to everything on the map, including terrain, units, structures, and features, giving maps a peculiar feeling, like, say, a feeling of taking place during the nighttime, a sunny day, or a very cloudy day. The 1st 3 parameters would control the redness, greenness, and blueness to apply to the filter, while the 4th parameter would control the alpha transparency setting.

setMapShadows()

This changes the map shadows' orientation (1st and 2nd parameters would control the x and y position of the sun, or moon if it's nighttime) and intensity (3rd parameter). For example, whenever the sun is shining directly over the map on a clear hot day, the shadows could be short, but sharply visible. On the other hand, if the day is very cloudy, or it's nighttime with no moon, then there could be no shadows present.

These 4 functions, if added in, would allow modders to be able to run a special rules.js file that, on game-start, would apply a particular weather effect, skybox, color filter, and/or shadow setting to either a particular map, or to any map that contains certain special "tag" objects. These tags could be special features that are invisible to players, but can allow mapmakers to set which skybox, weather effects, brightness, and/or shadows they'd like their map to use by default, without having to run a so-called map-mod.

[aubergine]

You could just use labels on map locations, and the mere presence of those labels (detected by enumLabel() function) would let you know what weather, etc., to use.

[Per]

You can already set lighting parameters to change the map colour and sun position to set shadow direction. Don't remember if I already ported the weather stuff from wzscript or not, but if not that is on the TODO list. Is there an actual use case for the skybox function?

[Shadow Wolf TJC]

When I initially came up with these ideas for functions, it was initially so that modders and mapmakers could personalize certain maps in multiplayer, even if they're of the same tileset, without having to resort to using map-mods. However, in singleplayer, they could be used to change the time of day, weather, etc. in a single map (thus changing its mood) in-between multiple missions of a campaign, or even DURING certain missions of a campaign. (For example, if a sandstorm arrived during a mission, the player could be forced to ride it out until he/she could call for more reinforcements, then later in the mission, when the sandstorm subsides, the player could be required to take out an enemy base.)

[Per]

Turns out I had not ported the sun and weather functions from wzscript yet. Did that now, in cb8730010fe0f28e8f5c0a99aec2178557533d5d.

[Per]

Ah, cool. Last time I used it it threw an exception if object didn't exist.

Returning NULL is what it should be doing. I did not actually test or read the code to see if it actually does.

Update: It will throw an exception, and it will assert fail if built in debug mode. There is no easy fix for this. As I said before, this function is a terrible hack, and should not be relied upon.

If need be, I can make a function objOnMap(id, player, object type), or something along those lines, that will simply return NULL if not found and probably will probably be an order of magnitude faster, and it will only find units on the map, not in all lists (off mission, inside transporters, in limbo...) like objFromId(). Yes, you need all three parameters, that's why it can be reasonably slow, rather than possibly game breakingly slow like objFromId().

But still, that is not how the scripting system was designed to be used...

[Per]

debugActive() function

Returns:
* true -- debug mode is active
* false -- not active

Use cases:

* AI scripts choosing whether to converse with enemy players or not based on debug mode
* Scripts outputting extra info to console/debug/chat when in debug mode

By debug mode, do you mean game is in cheat mode? Or built with debug symbols?

[aubergine]

Cheat mode (ie. Shift + Backspace)

[raycast]

Is there an actual use case for the skybox function?

I can imagine a single player map having nuke explosion(s). That might even temporarily white-out your screen, EMP all units, and then set the sky box to have a nuke mushroom somewhere and enable snow? Although for maximal coolness, one would probably need to actually play an animation on the skybox. I can imagine this to be a bit tricky with getting the texture management good for slow graphics boards.

[aubergine]

Did someone mention nuke? http://www.youtube.com/watch?v=_f47ufX1DSc

[aubergine]

eventDroidMove(droidObj)

Triggered when a droid (owned by 'me') enters a new map tile.

I'm currently tracking droid movements the hard way - with a timer that does enumDroid() then checks each of them to see if they are on a new tile.... long story, don't ask.

[aubergine]

getWeather(), getSunPosition(), getSunIntensity() functions

Return the current environmental effects.

For getSunPosition and getSunIntensity, return an object with relevant parameters. getWeather returns weather constant.

Already working on an API to do cool stuff with the weather/sun

setAmbientSound(soundID), getAmbientSound(soundID), eventAmbientSoundEnd(soundID)

Primary use to play howling wind, rain, etc., as a low-volume background sound. Situation Report messages (via playSound()) would play over the top of it, maybe automatically reducing the volume of ambient sound temporarily to aid clarity of SitRep audio?

When setting ambient sound, current ambient sound (if present) fades out over period of 2 seconds, 1 second gap, then new sound fades in over 3 seconds. (might need to tweak that but should be ok for starters).

setWind(angle, elevation, speed), getWind()

Used to apply wind effects to rain, snow and maybe even VTOLs?

Angle is degrees (or radians if easier?) referenced from north = 0º. Elevation (is there a more apt technical term?) is, well, obvious, as is speed.

Amount param on setWeather()

Currently weather is hardly noticeable. It would be nice if we could have some control over the number of particles (within reason), for example to turn gentle snow in to a blizzard.

When applied, the "amount" gradually increases or decreases from it's current value to the desired value. If there is danger of game lag, the amount would be limited to avoid lag.

In the distant future, this could be used to affect things like construction speed -- torrential rain or blizzards would impair construction. If construction speed calculations were un-hardcoded, JS could apply that effect itself.

setSnowColour(...), getSnowColour()

Ability to set snow colour (in similar way as sun colour can be set) would allow snow effect to be used for sand storms, fog, etc. There might be more obvious/effective approaches I'm not aware of (I'm a n00b when it comes to 3D stuff).

[Per]

Why do you need getters for weather/sun stuff?

I'll look into how much of the other parameters that can be changed. Don't expect too much...

[aubergine]

The getters mean that I can have multiple independent things happening with less hassle - they can get the current states to work out what to do next.

For example, if I script a lightning effect, I'll want to it to get the current sun state, then move the sun somewhere else and make it very bright (lightning flash in random part of the map), then return it to it's previous state afterwards. I might have code that move the sun based on time of day, and don't want to have to heavily integrate that with the code that does lightning effect.

I jotted down some rambling thoughts last night: https://warzone.atlassian.net/wiki/disp ... mmerse+API

[Duha]

Added new events (3.2 only):
eventGameSaving() - An event that is run before game is saved. There is usually no need to use this event.

Is it possible to send scope(data that will be saved) to eventGameSaving? For debugging.

*fix misspeling