Steam Community :: Guide :: NPC Programming Extender Guide

Store Page

Space Engineers

All Discussions Screenshots Artwork Broadcasts Videos Workshop News Guides Reviews

Space Engineers > Guides > Meridius_IX / Lucas's Guides

32 ratings

NPC Programming Extender Guide

By Meridius_IX / Lucas

This guide will explain what new features are available to NPC Drones and how to add them to your scripts.

Award

Created by

Meridius_IX / Lucas
Offline

Category: Modding or Configuration, Workshop

Languages: English

Posted

1 Jun, 2018 @ 2:50pm

2,820	Unique Visitors
77	Current Favorites

Guide Index

Overview

What is the NPC Programming Extender?

Can Target Fly

Change Grid Ownership To New Faction

Chat to Players

Check NPC Ownership

Create Items In Block Inventory

Create Particle Effect

Despawn NPC Grid(s)

Get All Allied Grids

Get All Enemy Grids

Get MyDetectedEntityInfo From EntityId

Get Nearest Allied Grid

Get Nearest Enemy Grid

Replenish Ice Inventory

Track Entity By ID

Comments

What is the NPC Programming Extender?

This mod adds new functionality to NPC Owned drones. The guide below contains some pre-scripted methods that can easily be added to your NPC scripts to expand their functionality.

Can Target Fly

Description

This method will check the grid of the provided entity ID to see if it is capable of flight. This does a check for gyros, thrust in each direction, and a ship controller.

Global Variables Required

None.

Method Arguments

long entityId //This is the EntityId that you want to get the Coordinates of.

Method Script

bool CanTargetFly(long entityId){ try{ Me.CustomData = entityId.ToString(); return Me.GetValue<bool>("NpcExtender-TargetCanFly"); }catch(Exception exc){ return false; } }

Change Grid Ownership To New Faction

Description

This method will change ownership of the grid and any sub-grids attached. Ownership is changed by specifying a Faction Tag in the Global Variable section of your script. Once this method is run, it's best to stop the script from processing any further since it will automatically be recompiled (required after an ownership change).

Global Variables Required

string factionTag = "SPRT"; //Replace With Desired Faction Tag

Method Arguments

None.

Method Script

bool ChangeNPCFaction(){ try{ Me.CustomData = factionTag; return Me.GetValue<bool>("NpcExtender-ChangeFactionRequest"); }catch(Exception exc){ return false; } }

Chat to Players

Description

This method allows the NPC to send a message to players using the in game chat interface. The message will display for any player within the range of the NPCs active antenna. If the NPC does not have an active antenna, the message will not display for any player. It is also possible to specify the name of a custom audio clip that will play along with the chat message (not required).

Global Variables Required

Please ensure you have the following global variable(s) in your script:

string lastChatSent = "Default"

Method Arguments

string message //This is the message that is sent via chat string author //This is the name of the 'sender' that appears with the chat message string audioClip //This is the SubtypeId of the audio definition you want played with the message

Method Script

bool SendChatMessage(string message, string author, string audioClip = ""){ if(message == lastChatSent){ return false; } lastChatSent = message; double broadcastDistance = 0; var antennaList = new List<IMyRadioAntenna>(); GridTerminalSystem.GetBlocksOfType<IMyRadioAntenna>(antennaList); foreach(var antenna in antennaList){ if(antenna.IsFunctional == false || antenna.Enabled == false || antenna.EnableBroadcasting == false){ continue; } var antennaRange = (double)antenna.Radius; if(antennaRange > broadcastDistance){ broadcastDistance = antennaRange; } } if(broadcastDistance == 0){ return false; } try{ string sendData = message + "\n" + author + "\n" + broadcastDistance.ToString() + "\n" + audioClip; Me.CustomData = sendData; return Me.GetValue<bool>("NpcExtender-ChatToPlayers"); }catch(Exception exc){ return false; } }

Check NPC Ownership

Description

This method will check if the programmable block calling it is part of an NPC faction. Valid NPC factions must not have human players as members and cannot be set to Accept Humans. If the block belongs to a valid NPC, the method will return true, otherwise it will return false. If you want to check ownership by a specific NPC faction, you can provide the faction tag in the method argument.

Global Variables Required

None.

Method Arguments

string faction //If provided with a faction tag, the method will only check ownershi by that faction. If left blank, it will check ownership against any valid NPC faction

Method Script

bool CheckIfNPC(string faction = ""){ try{ if(faction == ""){ return Me.GetValue<bool>("NpcExtender-IsOwnedByNPC"); }else{ Me.CustomData = faction; return Me.GetValue<bool>("NpcExtender-IsOwnedByFaction"); } }catch(Exception exc){ return false; } }

Create Items In Block Inventory

Description

This method allows you to create an add inventory items to any block on the NPC grid. This could be used to replenish ammo or uranium, or any other use you can think of.

Global Variables Required

None.

Method Arguments

string type //This should be the objectbuilder of the item you want to produce. Accepted Examples Below: //MyObjectBuilder_Ore //MyObjectBuilder_Ingot //MyObjectBuilder_Component //MyObjectBuilder_AmmoMagazine //MyObjectBuilder_PhysicalGunObject //MyObjectBuilder_OxygenContainerObject //MyObjectBuilder_GasContainerObject string subtype //This should be the subtype of the item you want to produce float amount //This should be the amount of the item you want to produce long blockEntityId //This should be the entity ID of the block you want to add the produced item(s) to.

Method Script

bool CreateItemInBlockInventory(string type, string subtype, float amount, long blockEntityId){ Me.CustomData = type + "\n" + subtype + "\n" + amount.ToString() + "\n" + blockEntityId.ToString(); try{ return Me.GetValue<bool>("NpcExtender-CreateItemInInventory"); }catch(Exception exc){ return false; } }

Create Particle Effect

Description

This method allows the NPC to create a particle effect at a set of coordinate or attach it to the coordinates of a specific entity.

Global Variables Required

None.

Method Arguments

string effectName //This should be the SubtypeId of the particle effect you want to create. Vector3D effectCoords //These are the coordinates of where the particle effect should be created. long effectEntityId //If an entity ID is provided, its position will be used instead of the effectCoords value (set effectCoords to equal -new Vector3D(0,0,0)-).

Method Script

bool CreateParticleEffect(string effectName, Vector3D effectCoords, long effectEntityId = 0){ Me.CustomData = "ParticleEffectRequest\n" + effectName + "\n"; if(effectEntityId != 0){ Me.CustomData += effectEntityId.ToString(); }else{ Me.CustomData += effectCoords.ToString(); } try{ return Me.GetValue<bool>("NpcExtender-PlayParticleEffect"); }catch(Exception exc){ Echo("Hard Fail NpcExtender-PlayParticleEffect"); Echo(exc.ToString()); return false; } }

Despawn NPC Grid(s)

Description

This method will attempt to despawn the NPC grid, along with any attached sub-grids. In order to be eligible for despawn, the grid must not contain any blocks owned by human players.

Global Variables Required

None.

Method Arguments

None.

Method Script

bool AttemptDespawn(){ try{ return Me.GetValue<bool>("NpcExtender-DespawnDrone"); }catch(Exception exc){ return false; } }

Get All Allied Grids

Description

This method will search all near-by grids that are part of the same faction as the NPC and will return a list of all eligible entity IDs. It is possible to limit the search to a certain distance. If the search cannot find any eligible grids, it will return an empty list.

Global Variables Required

None.

Method Arguments

double distanceToCheck //The search will only check grid within this distance of the NPC. Default value is 15000 meters.

Method Script

List<long> GetAllAlliedGrids(double distanceToCheck = 15000){ try{ Me.CustomData = distanceToCheck.ToString(); return Me.GetValue<List<long>>("NpcExtender-GetAllAllies"); }catch(Exception exc){ return new List<long>(); } }

Get All Enemy Grids

Description

This method will search all near-by grids that are considered hostile to the NPC and will return a list of all eligible entity IDs. It is possible to limit the search to a certain distance, as well as target grids of a specific faction. If the search cannot find any eligible grids, it will return an empty list.

Global Variables Required

None.

Method Arguments

string specificFaction //If a faction tag is provided, only grids with matching tag will be searched. Default Value is "None". double distanceToCheck //The search will only check grid within this distance of the NPC. Default value is 15000 meters.

Method Script

List<long> GetAllEnemyGrids(string specificFaction = "None", double distanceToCheck = 15000){ try{ Me.CustomData = specificFaction + "\n" + distanceToCheck.ToString(); return Me.GetValue<List<long>>("NpcExtender-GetAllEnemies"); }catch(Exception exc){ return new List<long>(); } }

Get MyDetectedEntityInfo From EntityId

Description

This method allows you to submit an entity ID and have it return a MyDetectedEntityInfo for that target entity.

Global Variables Required

None.

Method Arguments

long entityId //The entity ID of the object you want to retrieve MyDetectedEntityInfo on.

Method Script

MyDetectedEntityInfo GetMDEI(long entityId){ try{ Me.CustomData = entityId.ToString(); return Me.GetValue<MyDetectedEntityInfo>("NpcExtender-GetDetectedEntityInfo"); }catch(Exception exc){ return new MyDetectedEntityInfo(); } }

Get Nearest Allied Grid

Description

This method will search all near-by grids that are part of the same faction as the NPC and will return the entity ID of the closest one found. It is possible to limit the search to a certain distance. If the search cannot find any eligible grids, it will return a value of 0.

Global Variables Required

None.

Method Arguments

double distanceToCheck //The search will only check grid within this distance of the NPC. Default value is 15000 meters.

Method Script

long GetNearestAlliedGrid(double distanceToCheck = 15000){ try{ Me.CustomData = distanceToCheck.ToString(); return Me.GetValue<long>("NpcExtender-GetNearestAllied"); }catch(Exception exc){ return 0; } }

Get Nearest Enemy Grid

Description

This method will search all near-by grids that are considered hostile to the NPC and will return the entity ID of the closest one found. It is possible to limit the search to a certain distance, as well as target grids of a specific faction. If the search cannot find any eligible grids, it will return a value of 0

Global Variables Required

None.

Method Arguments

Method Script

long GetNearestEnemyGrid(string specificFaction = "None", double distanceToCheck = 15000){ try{ Me.CustomData = specificFaction + "\n" + distanceToCheck.ToString(); return Me.GetValue<long>("NpcExtender-GetNearestEnemy"); }catch(Exception exc){ return 0; } }

Replenish Ice Inventory

Description

This method will automatically add Ice to any of the O2/H2 Generators it finds on the NPC grid. For large grid generators, it will set the Ice inventory to 10,000 and it will set small grid generators ice to 2,700.

Global Variables Required

None.

Method Arguments

None.

Method Script

bool FillGasGenerators(){ try{ return Me.GetValue<bool>("NpcExtender-IceRefill"); }catch(Exception exc){ return false; } }

Track Entity By ID

Description

This method allows you get the Vector3D coords of an entity by providing the EntityId in the argument. If the entity cannot be found with the provided EntityID, it will return a Vector3D with the coords 0,0,0.

Global Variables Required

None.

Method Arguments

long entityId //This is the EntityId that you want to get the Coordinates of.

Method Script

Vector3D GetTrackedEntityPosition(long entityId){ try{ Me.CustomData = entityId.ToString(); return Me.GetValue<Vector3D>("NpcExtender-TrackEntity"); }catch(Exception exc){ return new Vector3D(0,0,0); } }

7 Comments

< >

Thomas Jefferson 20 Aug, 2018 @ 5:38pm

Ah, perfect, thanks!

Meridius_IX / Lucas [author] 20 Aug, 2018 @ 3:28pm

If you'd like, feel free to crack open the Reavers mod or the Attack of the Uncooperative Drones mod - both of these mods use it to switch to a custom faction.

Thomas Jefferson 20 Aug, 2018 @ 3:02am

No matter what I try, I cannot get the faction change script to function properly. Is there a complete example of it being used in an actual in-game script?

Aggelus 15 Jun, 2018 @ 9:31am

Thanks for the reply.
So I believe that the only way to put a ship into a faction created by the user, would be to edit it manually inside a map for the faction created "NURS" to export it to Blueprints and then to correct the SBC.
And then she would be the faction I want.
I thought there would be some code inside the .SBC that would indicate the faction but did not find.

Meridius_IX / Lucas [author] 15 Jun, 2018 @ 7:38am

These methods wouldn't be used in the Scripts folder. They're setup to be added to programmable block scripts. At some point in the near future, I'll be transitioning this guide to GitHub GIST, since it seems copying code from steam guides created sloppy formatting.

Once everything is tidied up, I'll be posting some example scripts for stuff like changing factions.

Aggelus 15 Jun, 2018 @ 6:56am

I am building a MOD and wanted all the ships belonging to the NURS faction, I have already created the Factions.sbc in the DATA folder and already have the ships in the Prefabs folder along with the PirateAntennas.sbc and SpawnGroups.sbc plus they appear as pirates.
How would I create a CS that placed in the Scripts folder solved this problem?

Blacky Watchy 5 Jun, 2018 @ 11:34am

what do I must to put in "Exeption"?

< >