Scripting API requests

[Hammelpilaw]

When playing online every player got some sectors wich always be kept alive. The order wich sectors will be alive is hardcoded. It would be awesome for modders to be able to change the order.

 

The reason is simple: When you got many stations in different sectors you do not need all the secors to be up because the production will be calculated when the sector gets restored from disk. But your salvage ship in another sector does not keep the sector alive, you have to calculate how many ships you need there to make its score bigger then the stations in other sectors. This is only one example, there are many situations where I wished I could modify it.

 

Some examples what Im thinking of.

 

Manually define the sector score.

function getSectorUpkeepScore(Entities, Player)  local score = 0
  for _,entity in pairs(Entities)
    if entity.factionIndex == Player.index then
      if entity.hasScript("salvage.lua") then
        score = score + 5
      end
      -- do some more stuff
    end
  end
end

 

 

Manually define the entities score

function getEntityUpkeepScore(Entity, Player)
  -- Calculate entity score
end

 

 

Also it would be great to see wich sectors are alive.

Player():getAliveSectors()
-- or
Server():getAliveSectors(playerIndex)

[Rinart73]

Some more API requests :)

 

1. Please add "initializationFinished" for Sector objects.

Reasons: Modders need to know when sector was completely generated. Current workaround is a mix of onRestoredFromDisk + onPlayerEntered, which is not bad, but not instant the first time sector is being generated.

 

2. Also it would be very good to know when Player is in building mode (at least on client side).

Reasons: Modders could stop drawing custom UI elements that are not needed in building mode (or start drawing useful bulding UI). For example both my Resource Display and Buffs mods are currently messing up building UI because they're overlaping it.

 

3. It would be great to have serverside player or alliance callbacks when player joins or leaves alliance.

Reasons: Currently we have clientside callback. Which means modders have to rely on player (which is bad)

 

4. Please add some sort of "invokeFunction" Entity-like method, and also "secure" and "restore" functions for "main.lua".

Reasons: Avorion really lacks centralized serverside mod controller, that would store data and would be accessible from any script. Adding functions that were mentioned above to the "main.lua" would turn this script into that mod controller. And mods would be able to communicate with each other efficiently!

Examples:

• My Galaxy Map QoL mod that is quite popular needs mod controller in order to store, save and give alliance map markers. Currently I have to rely on horrible workarounds, like bouncing the data between online members and the slightest desync can result in losing data. Having something like:
  

  ModController("ModName"):invokeFunction("functionName", arg1)

  would make everything much better.
  
• My Server Guard mod (will be used on reborn Rusty's Galaxy server) currently has to fetch server variable in "update" function every X seconds via "getValue" in order to transfer data from sector script to the "main.lua".
  

[koonschi]

1. Please add "initializationFinished" for Sector objects.

Do you need a callback for when the sector was first generated?

 

2. Also it would be very good to know when Player is in building mode (at least on client side).

Possible on the beta branch: Use the "onStateChanged" callback of client Player, which will give you 2 ints of the enum PlayerStateType

 

3. It would be great to have serverside player or alliance callbacks when player joins or leaves alliance.

This is planned. Due to structural refactorings on the client this was possible very early and "for free" so we added it for the client for now.

 

4. Please add some sort of "invokeFunction" Entity-like method, and also "secure" and "restore" functions for "main.lua".

invokeFunction() shouldn't be that much of an issue, secure() and restore() definitely are.

[Rinart73]

Do you need a callback for when the sector was first generated?

Basically, yes.  Current workarounds work almost fine (although onPlayerEntered makes it delayed), so it's a low-priority request.

 

Use the "onStateChanged" callback of client Player

Thank you.

 

invokeFunction() shouldn't be that much of an issue, secure() and restore() definitely are.

invokeFunction is much more important, since it would allow instant way of data transfer.

[MrKMG]

Simple Request:

 

Fill out the "Loot" object to have more than just "insert".  A mod idea I have is a system upgrade which will show you valuable targets. That could be determined by polling what loot is on a target entity. Currently, it's impossible to poll for any loot added via the "Loot(entity.index):insert".

 

Thanks!

[Shrooblord]

A function complementary to the Sector() and Entity() API's onRestoredFromDisk() (triggered when the Sector() or Entity() is read from disk and put into active memory). Let's call it onSecuredToDisk() for the purposes of this discussion. It would be called just before the Sector() or Entity() finishes saving to disk and unloads from memory.

 

It would be cool to be able to act upon the unloading of data from memory, such as triggering a "start simulations now" script, warning the player about the unloading status of a Sector, saving our own data somewhere else than in the secure() space so we still have access to it, a last-known-location type of thing... just knowing that a Sector has become unloaded the instant it happens, because we acted on the callback... the list goes on and on. So many cool use-cases.

 

EDIT:

 

An additional callback named something along the lines of onSecureToDisk() which triggers before the saving process begins. This would be used so you can make last-minute changes to a running script before the Sector() or Entity() is well and properly hermetically sealed. This callback is requested because Sectors and Entities can save to disk using secure() without unloading from memory, but it would be useful to act upon the case when and only when the Sector() or Entity() actually unloads from memory.

 

P.S.

Thanks to Hammelpilaw for the original spark of the suggestion.

[Rinart73]

Add one more value to the "PlayerStateType" - "UsesUI".

Initially I thought that "PlayerStateType.Interact" is set when player interacts with entities or opens UI windows. But apparently it's set only when player interacts with entities via dialogs.

"PlayerStateType.UsesUI" should be set when player opens UI windows: Player window, Ship window, custom windows added via "ScriptUI():registedWindow".

 

Reason: You show player resources when player opens any window. My mod needs to react to that, otherwise UI overlaps :/

[Shrooblord]

Expose StatsBonuses.Pilots to lua. Every other profession crewmen can have has been exposed, except this one. PilotsPerFighter exists, but fills a different role.

 

Reason: StatsBonuses.Engineers and related StatsBonuses exist for a good reason: they allow us to add Crew via System Module Upgrades, or some other "buffing" mechanic. Why should Pilots be excluded from this capability?

[Rinart73]

Add "onTextChangedFunction" for the "MultiLineTextBox" UI element.

 

:-\ I needed to limit max amount of characters player can use and without this callback I can only do it after player will do something else (like try to send the data).

[Rinart73]

Currently it's impossible to get some basic ship stats before they were affected by bonuses. Stats in "BlockStatistics" are either incomplete or require to use some formula that modders don't know.

• Hyperspace Reach - "BlockStatistics" has hyperspacePower and it seems that it's hyperspace calculation power from blocks. What does it mean? Is there some formula to transform it into hyperspace reach? (Nvm it's cubic root of "hyperspacePower")
  
• Hyperspace Cooldown - No stat or formula
  
• Hyperspace Recharge Energy - No stat or formula
  
• Shield Recharge Rate - No stat or formula
  
• Velocity - When it comes to Avorion stats, velocity is the max speed you can get. No stat or formula
  
• Acceleration - I thought that it's "trust" from "BlockStatistics" but I'm getting some weird numbers there
  
• Loot Collection Range - Tests show that it's somewhere between 0.95km and 1 km
  
• Radar Reach - It seems that default radar reach is 14?
  

[Rinart73]

Can we get a serverside variant of a Player's callback "onAllianceChanged(allianceIndex)"? Otherwise I have to attach "onNewMember" and "onMemberLeft" callbacks to every alliance and it's not great since Alliances get unloaded.

So if Alliance is unloaded and player accepts an invitation, "onNewMember" won't fire.

[Shrooblord]

I would love the ability to more precisely control what happens to System Module Upgrades. More specifically, I request:

• A hook to prevent the functionality that triggers the onUninstall() callback from occuring. In other words, prevent a Player from uninstalling an SMU and/or destroying it permanently.
  
• Force-install an SMU to a Player's Ship through scripts.
  
• Force-uninstall an SMU from a Player's Ship through scripts.
  

 

This is because, in certain conditions, we might want to permanently lock-in an SMU into their Ship. Think of vampiric / parasite systems, or exploitable uninstall-reinstall mechanics (when the SMU adds flat bonuses like Crew Workforce for crew such as Pilots and Boarders that might not be on-board the Ship at time of uninstallation) that could be fixed by preventing the uninstallation dead in its tracks.

 

Additionally, you could add cool questlines with upgrades becoming replaced by some corrupted version of them, and/or have nefarious characters forcibly install systems on your Ship that act like in-game spyware, etc..

 

EDIT:

Re: Force Uninstallation

 

You can actually force-uninstall an SMU; in the end they're just scripts added to your Ship. You can remove this script manually using removeScript().

 

Adding it using addScript() doesn't seem to be fully functional, as the script is loaded and added to the Entity, and when you pass it a sufficient seed and rarity, it runs without errors, but no SMU is ever physically added, and so no bonuses are added to the Ship.

 

Happy coding with this new knowledge! ^^

[Rinart73]

Force-install an SMU to a Player's Ship through scripts.

ShipSystem():addUpgrade(SystemUpgradeTemplate upgrade, bool permanent)

 

You can actually force-uninstall an SMU

ShipSystem():removeUpgrade(unsigned int slot)

[Rinart73]

Add a way to check if a faction (NPC or alliance) is loaded in memory on server-side.

[LoganDark]

https://www.avorion.net/forum/index.php/topic,6108.0.html

 

Summary: Allow invokeClient/ServerFunction to transfer Inventory, allow InventorySelection:fill() to accept an Inventory as an argument

[Rinart73]

It would be great to have "listFilesInDirectory" and "deleteFile" functions (BOTH on client and server) for operating files in the "moddata" and its subfolders.

[Bubbet]

function table getmodids()

Returns

    Returns a table of the mod-ids of mods that have modified the top-level script file that this function is called from.

 

A function kind of similar to the getScriptPath() we already have, except instead of returning the full path to the file in question, it returns the mod-ids of mods that have made modifications to said file.

 

It'd probably be nice to have a function similar to scriptPath() too, returning the mod-ids of the mods affecting the current file not the top level file.

[Bubbet]

Function for getting a players steamID, steamID3, and steamID64.

 

[alfuken]

I'd like to request to expose adding and altering of "Components" of the "Entity". Right now there is no way to add or alter a component of a ship. One can only add components when creating a ship via "ShipDescriptor". On "Entity" object you can only check if component exists, but you can't access that component.

 

Reasoning behind this: a lot of the balancing issues in game are related to extremely high ship speeds: basically all ships in the game can simply outrun fighters, torpedoes, missiles and even cannon shots - and that is... well... illogical, to say the least. This issue is causing a wide array of weapons practically unusable.

I wanted to make a mod that would either disable "boost" ability of the "Engine" component of every single ship, or limit the ship speed via "DirectFlightPhysics" component based on ship size. Turns out you can not permanently alter the "Engine" component of already created ship (hence can't disable boost), nor you can't add a "DirectFlightPhysics" component to a ship (was thinking about using it's maxVelocity property). Altering ship creation methods is not an option since it's done in so many different places in the code, that it would be an utter mess.

 

Hence the request: a bit more freedom of control over the created entities - expose adding/removing/setting/altering of Components on an Entity. And/or ability to get an "EntityDescriptor" instance of existing Entity in order to alter the underlying Entity.

[Paulquappe]

Some UI stuff would be kinda nice:

 

 

[*] Callbacks  for when an window is shown/hidden. I need the latter to implement a lock that will be released when the window is closed.

[*] SelectionItem with a string instead of an icon/texture

[*] Multiple selectable items in Selection or ListBox. Alternatively, labels that can be highlighted would also suffice (so I can implement it myself).

 

Reasoning behind this: a lot of the balancing issues in game are related to extremely high ship speeds:

 

I second that. Limiting maximum velocity could create some more "dogfighty"  battles.

[GaeBaeRae]

It would be really awesome to have some way of retrieving the list of currently selected BlockPlanBlocks when in build mode. My primary use case would be to apply a specific turret design to all selected turret blocks, but it would open up build mode modding immensely. 

[Sathaerz]

I'd like a way to sync faction traits between server and client. I've noticed that you can set faction traits server-side, but when you click on the diplomacy window the values have not been set client-side.

If there's a way to do this already, it's not clear based on the documentation / scripts. I'm trying to add some custom traits that get updated on the fly, and currently they are not getting set in the diplomacy window until the game is unloaded / reloaded which isn't ideal.

[koonschi]

Quote

I'd like a way to sync faction traits between server and client. I've noticed that you can set faction traits server-side, but when you click on the diplomacy window the values have not been set client-side.

If there's a way to do this already, it's not clear based on the documentation / scripts. I'm trying to add some custom traits that get updated on the fly, and currently they are not getting set in the diplomacy window until the game is unloaded / reloaded which isn't ideal.

There's no way to sync those. What you'd have to do is request those custom values in the diplomacy window from the server via invokeServerFunction() and on the server, respond with invokeClientFunction(), sending the data in the parameters.

[Sathaerz]

13 hours ago, koonschi said:

There's no way to sync those. What you'd have to do is request those custom values in the diplomacy window from the server via invokeServerFunction() and on the server, respond with invokeClientFunction(), sending the data in the parameters.

Oh, interesting. That... significantly changes how I'm going to have to write this.

Thanks for the quick reply. Appreciate it, as always.

EDIT: Is there a way to make sure it waits for the update to run before continuing the function? I still have to double-click before it shows the data, which is strange.

Edited September 22, 2020 by Sathaerz

[Sathaerz]

In addition to the question I edited into the last post, would a readable UIElement text be possible?

If not, I'd settle for a "return text" on the last line of Diplomacy:updateTraits(faction) - around line 1949.

[Sathaerz]

Another request: I'd like a way to get the random names the game generates internally for ships / factions, for scripting purposes.

EDIT: I looked through the documentation and I found this. I can't believe I missed that on the first pass.

Edited November 13, 2020 by Sathaerz