Edits and clarifications for lua-api.txt

[jrwarwick]

I found a couple of minor errors in lua-api.txt such as example argument order error and spelling error.
patch for the ones I am confident about:
0001-Minor-edits-and-clarifications-to-lua-api.patch.txt

Here are some others that I am not so certain about:

comms_channel_listen(name, channel, callback)

What does "name" mean when listening?

destroy_ship(ship_id)
Since this function is for NPC ships only, not player ships: what is the appropriate way to destroy the player ship? A hint left or reference in this function's explanation would be handy.

add_explosion(x, y, z, v, nsparks, time, victim_type, explosion_type);
What is argument v? An object ID of a (v)ictim?
Also, it might be helpful to briefly note whether this function is in fact purely cosmetic, or if it will induce any kind of damage or live/dead state changes, or any other game state side-effects (or not).

get_ship_attribute(id, attribute_name);
Example of how to get the currently set powerlevel and heat level of an engineering system.

Also, would this be a good place to discuss or request new lua api functions?

[smcameron]

Thanks! Committed as d1bb80c Minor edits and clarifications to lua-api.txt

What does "name" mean when listening?

Good question. I think I meant to use it to allow player ships to hail Lua controlled NPC channels when the player hailed the given name. However this is not totally implemented. If you grep for 'lua_channel.*name' you can find the places it is referenced. One of them is in meta_comms_hail() in snis_server.c, but the business end of that code just has a comment that says: "What to do here?" So I never finished it.

However, the name does serve a purpose, as you can register multiple listening functions on the same channel, and unregister them separately by name.

Lua scripts can hail the player (KALI.LUA does this as does DEMOLISHER.LUA.) It's a bit of a hack relying on knowing the special hailing message which snis_server snoops in process_comms_transmission().

what is the appropriate way to destroy the player ship?

That is a good question. I don't think there's a good way. You could move_object() them to the same coordinates as a planet, lol.

add_explosion(x, y, z, v, nsparks, time, victim_type, explosion_type); What is argument v? An object ID of a (v)ictim?

It is a ship type, one of these:

SHIPTYPES in snis:

        SHIP_CLASS_CRUISER 0
        SHIP_CLASS_DESTROYER 1
        SHIP_CLASS_FREIGHTER 2
        SHIP_CLASS_TANKER 3
        SHIP_CLASS_TRANSPORT 4
        SHIP_CLASS_BATTLESTAR 5
        SHIP_CLASS_STARSHIP 6
        SHIP_CLASS_ASTEROIDMINER 7
        SHIP_CLASS_SCIENCE 8
        SHIP_CLASS_SCOUT 9
        SHIP_CLASS_DRAGONHAWK 10
        SHIP_CLASS_SKORPIO 11
        SHIP_CLASS_DISRUPTOR 12
        SHIP_CLASS_RESEARCH_VESSEL 13

That list may be out of date, the real list is in share/snis/ship_types.txt, starting with 0 and counting up by 1 for each ship type. This looks like some ancient relic code here that controls the color of the sparks of the explosion depending on what type of victim was destroyed (see update_explosion() and do_explosion() in snis_client.c. Except it doesn't because the spark color is controlled by the material. This looks to be left over from before I even used opengl. Might control the spark color on the snis_limited_client, but now sparks are billboards, not meshes, so probably not even that.

Probably need to update the API around that area.

The explosion is purely cosmetic.

get_ship_attribute(id, attribute_name);
Example of how to get the currently set powerlevel and heat level of an engineering system.

If you run

make bin/print_ship_attributes
bin/print_ship_attributes

you will see the names and types (d = double, f = float, b = byte, w = 32bit int) of all the attributes.

impulse_temp = get_ship_attribute(id, "temperature_data.impulse_damage");
Value is 0 to 255.

Also, would this be a good place to discuss or request new lua api functions?

Yeah sure, you can ask for more Lua API functions.

[jrwarwick]

Thanks, @smcameron , very helpful. I have one more:
proximity callbacks cannot be stacked, correct? If you do this:

register_proximity_callback("pretty_close", oid1, oid2, distance); 
register_proximity_callback("closer_yet", oid1, oid2, distance); 

then "closer_yet" will get called, but "pretty_close" will not, correct?
It looks like I was successful in instead putting the call to "closer_yet" inside of the callback function pretty_close, to achieve chain proximity callbacks. Is that a safe thing to do?
A warning about only-one-callback per pair of objects would be handy.

[smcameron]

Correct. In snis_server.c it does this:

static double register_lua_proximity_callback(const char *callback,
                const uint32_t oid1, const uint32_t oid2, const double distance)
{
        struct lua_proximity_check *i, *last, *newone;

        last = NULL;
        for (i = lua_proximity_check; i != NULL; i = i->next) {
                /* Replace values if callback already exists */
                if (oid1 == i->oid1 && oid2 == i->oid2) { <--- this means you cannot stack multiple proximity callbacks.
                        if (i->callback)
                                free(i->callback);
                        i->callback = strdup(callback);
                        i->distance2 = distance * distance;
                        return 0.0;
                }
              ...

[smcameron]

Is that a safe thing to do?

Without seeing your code.... I think so.

[smcameron]

Updated lua-api.txt c12361f Clarify a few questions about lua-api.txt

That addresses some of the things mentioned above.

[jrwarwick]

Is there a supported way to determine the population of Starbases and Planets? As far as planets, I think I'm seeing that population is not a 'real' property, but instead intended to exist at the lua level, so to speak. If that is so, maybe some kind of combination of planet description and presence or absence of government property?

[smcameron]

Not really. Planets don't have anything for population. starbases have a lifeform_count field, but I don't think it's accessible from lua. NPC ships also have a lifeform_count field which you can get from lua with get_ship_attribute(). The lifeform count is just something to show in science when you scan a ship or starbase, it doesn't really have any significance in the game. I don't know that it would make sense to show a population for a whole planet when scanning it. Maybe when you ask the computer to describe a planet. But those planet descriptions are pretty silly.

You say "I think I'm seeing that population is not a 'real' property, but instead intended to exist at the lua level.."

I don't see any mention of population in any lua scripts, so I think that "population" of planets just plain doesn't exist at all. It's possible I'm missing something... what are you looking at that makes you think there is some notion of population for planets? I'm not seeing anything regarding population of planets, so I don't think there was any intention about it.

Could add a population count to planets pretty easily. The data for planets is only transmitted to the clients once I think because they never change (rotation is on the client only, I think.) OTOH, I don't know if adding a population count to planets adds very much to the game.

[jrwarwick]

Yes I see your point. This is wait I thought I was seeing. As far as the "Lua level" I was looking at saving planet erph, but I guess that is limited to whole cities of conceptual population.

…

--Justin

On Thu, Mar 26, 2020, 13:57 smcameron ***@***.***> wrote: Not really. Planets don't have anything for population. starbases have a lifeform_count field, but I don't think it's accessible from lua. NPC ships also have a lifeform_count field which you can get from lua with get_ship_attribute(). The lifeform count is just something to show in science when you scan a ship or starbase, it doesn't really have any significance in the game. I don't know that it would make sense to show a population for a whole planet when scanning it. Maybe when you ask the computer to describe a planet. But those planet descriptions are pretty silly. You say "I think I'm seeing that population is not a 'real' property, but instead intended to exist at the lua level.." I don't see any mention of population in any lua scripts, so I think that "population" of planets just plain doesn't exist at all. It's possible I'm missing something... what are you looking at that makes you think there is some notion of population for planets? I'm not seeing anything regarding population of planets, so I don't think there was any intention about it. Could add a population count to planets pretty easily. The data for planets is only transmitted to the clients once I think because they never change (rotation is on the client only, I think.) OTOH, I don't know if adding a population count to planets adds very much to the game. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#272 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AALAR5HRW5RDIDSZFFXB2PLRJO6SFANCNFSM4LPUP6FA> .

[jrwarwick]

Your guidance on the ship attributes was really helpful. One thing I couldn't figure out though: how to get science_selection (which appears to be part of the the bridge, not the ship, so to speak). It looks like bridge state and ship attributes are handles separately. I do not yet understand how separately. Is there a supported way for mission scripting to determine player's current science selection?

[smcameron]

There is an "object-scanned-event" that you can register a callback for.

https://github.com/smcameron/space-nerds-in-space/blob/master/doc/lua-api.txt#L138

Something like:

function record_object_scan_event(player_ship_id, object_id)
   -- do whatever you need to do when some particular object is scanned.
end

register_callback("object-scanned-event", "record_object_scan_event");

Looks like none of the scripts currently use it though. Also looks like it doesn't work for waypoints. And I think it probably doesn't let you know when the player has deselected an object, so you can get notified at the time of selection, but you won't know if the object later got de-selected.