Oolite Bulletins

I have a few questions.

What's the best way to identify in JS what equipment an NPC ship has? Specifically in this case I'm thinking about the system upgrades such as increased energy and recharge rate because I understand they don't actually set a status flag in the ship entity. I'm assuming that 3rd party upgrades work by awarding equipment and therefore can be identified through the equipment list.

Given how 3rd party NPC upgrades work is there any move to standardize the way NPC ships acquire upgrades by representing everything at an equipment or status flag level? I note in the wiki there are a couple of properties that will report the plist keys in the upcoming version 1.79. Is there a release date proposed for that version?

Finally are we free to branch from the GitHub repository? If we do is there a way of submitting new code for review for future versions?

Thanks everyone

realbrit70 wrote:

What's the best way to identify in JS what equipment an NPC ship has? Specifically in this case I'm thinking about the system upgrades such as increased energy and recharge rate because I understand they don't actually set a status flag in the ship entity. I'm assuming that 3rd party upgrades work by awarding equipment and therefore can be identified through the equipment list.

You can do this using ship.[url=http://wiki.alioth.net/index.php/Oolite_JavaScript_Reference:_Ship#equipmentStatus]equipmentStatus[/url](key) as you would for the player ship.

Many items of core equipment currently do nothing when placed on an NPC ship, though. Some of the ones that don't probably should, though exactly what they should do is harder to say. Since NPCs don't have shields (yet) the two shield booster equipment items currently increase their energy (and recharge, in the military case), but they have the same name as the player items.

3rd-party equipment is very difficult for NPCs to use, other than missiles, since equipment use is very tightly linked in to the AI and the underlying behaviours.

realbrit70 wrote:

I note in the wiki there are a couple of properties that will report the plist keys in the upcoming version 1.79. Is there a release date proposed for that version?

2014 is what I'm aiming for.

realbrit70 wrote:

Finally are we free to branch from the GitHub repository? If we do is there a way of submitting new code for review for future versions?

Absolutely. Code can be submitted as a pull request (it's worth discussing ideas on here first, if it's not a bugfix).

realbrit70 wrote:

What's the best way to identify in JS what equipment an NPC ship has?

You can get the list using a for cycle on the ship.equipment array, I think it is works exactly as a status flag. There is an advanced example in the shipWillLaunchFromStation function of  towbar.js: if you set $TowbarDebug=true then you get a full equipment list from all ship in the system into Latest.log when you undock.

The 3rd party upgrades will not work always automatically by awarding the equipment, for example when I wanted to award [wiki]Q-Charger[/wiki] to NPCs then I changed the code in this OXP also because originally was written to player only. But we can help more if you talk further from your plans.

My plans are now fourfold.

1. One of the first things I thought of upon seeing the changes implemented in 1.77 was that accuracy could be used as the basis of an Galactic Federation Elite rating for each NPC. Based on the information in the Wiki I'm using a base rating of Harmless for accuracy ratings under 5 up to a base rating of Competent for accuracy 9+. My intention is to then add to that rating based on the number of combat upgrades an NPC ship carries, hence the question on being able to determine what upgrades a specific ship carries especially upgrades to the max energy and recharge rate that do not seem to have related equipments in the equipment list. My thought was that an ECM system is vital and thus improves rating +1 rank on it's own. After that I felt that a ship carrying 2 other upgrades such as Military Laser, Increased Energy, Increased Recharge, Fuel Injectors, etc. should get an additional +1 and one carrying 4+ upgrades should get a final +1 for a maximum of +3. This way an NPC with an accuracy of 9+ and a ship with an ECM system and 4+ upgrades would be rated as Elite. I don't feel this will disrupt game balance too much because at lower ratings the rating could be due to either the pilot skill (represented by accuracy) or the hardware the pilot is flying, thus still leaving room for doubt in the mind of the player.

2. I'm implementing this algorithm in an OXP that adds a Threat Scanner upgrade equipment for both players and NPCs. The scanner requires both the STE and Bounty Scanner upgrades to the base scanner and is expensive to help maintain game balance. The scanner replaces the Bounty Scanner timer functionality with an event based functionality using the new shipBountyChanged event to update the bounty on screen if necessary. Right now I have the OXP reporting Bounty and Elite rating, though the Elite rating is based purely on the accuracy right now.

3. I'm also going to implement an OXP to implement a form of Bounty Scanner and Threat Scanner on NPCs. NPCs with at least 2 ship upgrades would automatically be given the Bounty Scanner and those with 4+ upgrades would be given the Threat Scanner. This functionality would be used to replace certain parts in some AI, for example in the pirateAI I would change the LURK functionality to perform a different performGroupOddsVersusTarget check based on an algorithm along the lines of:

Average Pirate Group Elite Rating - Average Target Group Elite Rating + Number in Pirate Group - Number in Target Group + Target Bounty / 10 + Pirate Hold Space / 10

With a result > 1 being ODDS_GOOD and result -1 < > 1 being ODDS_LEVEL and < -1 being ODDS_BAD. Rational here is that the pirates are more likely to attack for a bounty or if they have a lot of hold space to fill.

4. Finally I can't imagine I'm the only person looking for a way to easily determine the equipment carried by an NPC, not to award or manipulate the equipment necessarily but in order to incorporate the knowledge of that equipment into their own OXPs. Therefore I want to take a look at the code and propose a common way of handling awarding equipment to an NPC that won't necessarily changed the way the current upgrades work but will provide scripters an easy way to identify and hook to those equipments.

A general advice first:
Are you aware of the scripting documentation on the Wiki? Please take your time to ingest it (all of it, basically) and some of the general information on scripting, before you begin your project, and while you go along. Personally, when I'm OXPing, I have a lot of these Wiki documents opened and ready in over a dozen browser tabs for fast and easy referencing. I recommend this to all OXPers.

If you go through the documentation, you will soon notice that the equipment array is a standard property of all ships in the game, as documented here. The same goes for forwardWeapon and its three sisters, which I'm not going to link individually. These properties aren't even particularly new. They exist since Oolite 1.74 in June 2010. And when searching for a property of NPC ships, the Ship class documentation page is really the very first page where you ought to look.

One of the first things I thought of upon seeing the changes implemented in 1.77 was that accuracy could be used as the basis of an Galactic Federation Elite rating for each NPC.

That's a fascinating idea, and I also like your approach going from accuracy, and taking weapons and equipment into account. This certainly makes sense.

A couple of things you should keep in mind, though:

1) Elite pilots are rare. There are not many of them in the whole Ooniverse, not more than some handfuls. And not all of them will be flying all the time. They're more the stuff of legends than something that an ordinary space farer actually sees. And if he does get lucky enough to fly alongside an Elite pilot, he'll be bragging about it in ZeroG-Bars for the rest of his life. Thus an encounter with an Elite pilot should be exceedingly rare.

2) The system populator only adds ships with an accuracy between -5 and 5, if I'm recalling correctly. Thus, in the higher ranks you'll only have OXP ships that have their accuracy specifically set. Which effect this has on the rarity (or abundance) of "Deadly" and "Elite"-ranked pilots during normal game play I cannot say. But this is where I guess you will need to do a fair amount of balancing. I for one wouldn't want to fly in a Ooniverse where every second ship I meet is "Elite". If "Elite" pilots are a dime for a dozen, the whole ranking is in danger of losing its meaning.

3) The Elite rating isn't advertised, and I assume most Elite pilots to fly "incognito" almost all of the time. Whether someone is "Dangerous" or "Elite" can't be determined from the outside, other than by the look of their ship. And that one can be deceptive. I'd be totally opposed to a mechanism that for instance displays a pilot's Elite rating next to the ship name.

4) Therefore I'm a little skeptical with regards to basing combat tactics on the opponent's Elite rating, because usually this rating won't be known to anyone else. A pirate group will attack a single worn-down Cobra III, and will only find out that the pilot was "Elite", because they'll all be dead or disabled after the fight. This is—I think—how it should be, and it's also realistic.

5) When binding the Elite rating to the accuracy property, there's the problem of how you determine your opponent's accuracy in the first place. Yes, I know that the NPC script can just look it up, but that's not realistic, that's an exploit. In-Ooniverse, only magic could tell you how accurate your opponent is, before you've actually fought him. You will only find out through observation during the fight how often your opponent misses and how well he hits. You can't know that beforehand, and NPCs shouldn't be able to, either.

6) The same goes for equipment. You can't look into your opponent's ship and determine which equipment he has installed, and NPCs shouldn't be able to, either.

7) And finally: How will a pirate group measure their odds against the player by this method? The player ship's accuracy property does exist, but is meaningless. It doesn't allow any guess as regards the player's Elite rating.

realbrit70 wrote:

My plans are now fourfold.

Points 1 and 3 I'd advise not spending too much time on as 1.79 already has a built-in way to do those fairly similar to what you're thinking of. For point 4:

realbrit70 wrote:

Therefore I want to take a look at the code and propose a common way of handling awarding equipment to an NPC that won't necessarily changed the way the current upgrades work but will provide scripters an easy way to identify and hook to those equipments.

Awarding and identifying equipment for an NPC is pretty straightforward. The trick is to get them to do something sensible based on it. Here's the state of the core equipment:

1. NPCs can use as if they were a player: Fuel, Missiles, Mines, Lasers, ECM systems, Escape pods, Fuel Injectors, Cloaking device, Large Cargo Bay*
2. NPCs can have this, but the effect is different from the player: shield boosters, military shield boosters
3. NPCs currently act as if they have this equipment whether it is installed or not. Actually adding it makes no difference: multi-targeting system, target system memory expansion, advanced space compass, external heat shielding**, docking computers
4. Installing this equipment to NPCs has no effect: extra energy unit, naval energy unit, advanced navigational array, scanner targeting enhancement, wormhole scanner, galactic hyperdrive, OXP equipment
5. NPCs cannot fit this equipment: passenger berths

* but in practice rather than fit the equipment this is done by giving the NPC a higher base capacity in shipdata.plist
** only some NPCs act as if they have this. It's still independent of the item.

Category 2 is because NPCs don't have shields, so these give extra energy and recharge rate instead.
Category 3 and 4 probably should be done properly, at least for most of them: suggestions on what NPCs should do with that equipment (or not do without it) are welcome.

OXP equipment is trickier - how do you explain to the AI what the properties of the equipment are and how they should affect its behaviour?

Commander McLane wrote:

That's a fascinating idea, and I also like your approach going from accuracy, and taking weapons and equipment into account. This certainly makes sense.

Indeed, it makes so much sense that it's already in 1.79. With regard to your questions about "how do they know?":

Commander McLane wrote:

4) Therefore I'm a little skeptical with regards to basing combat tactics on the opponent's Elite rating, because usually this rating won't be known to anyone else. A pirate group will attack a single worn-down Cobra III, and will only find out that the pilot was "Elite", because they'll all be dead or disabled after the fight. This is—I think—how it should be, and it's also realistic.

In 1.79 there's a ship.threatAssessment(Bool full) function (not yet documented). The NPCs do a full check for ships in their group, and a non-full check for others - but a non-full check returns the same information as a full check if the ship is in combat. Accuracy (or, for the player, a number based on their Elite rating and on a similar scale to the NPC accuracy variable) is only used in the full check, as are many details of equipment and armament

You quite often get the smaller NPC pirate packs threatening the player, having one or two of their ships blown away at long range by a military laser, and suddenly remembering they had an important appointment on the other side of the system.

I think to reveal the accuracy of an NPC to the player is good only if he is a mission target or there are some connection with a specific character or group but not generally (+1 to McLane's words).

Improving NPC AI is always good and imaginable a personal or spy contact between the NPCs in the backgroud to confirm the usage of these data. The combat level of a maxed NPC is still far less than a human Elite player imho.

cim wrote:

[*]Installing this equipment to NPCs has no effect: extra energy unit, naval energy unit

What is the reason of this? I think NPCs deserve to get the same recharge bonuses.

Norby wrote:

cim wrote:

[*]Installing this equipment to NPCs has no effect: extra energy unit, naval energy unit

What is the reason of this? I think NPCs deserve to get the same recharge bonuses.

As with the large cargo bay, this equipment is generally pre-accounted for in the NPC's shipdata.plist. For example, the Viper Interceptor has an energy recharge rate of 6 - which I assume is 3.3 base plus an extra energy unit.

If in later versions NPCs have shields and can take equipment damage when their shields are down, it will become more important to implement this consistently with the player. For now it makes no difference.

Just my two-pennies-worth.
I would be wary of falling into the Too Much Information trap. I personally would not want to know much about the ships around me, just as I don't want them knowing much about me. I sometimes find that even the STE telling me the legal status of other ships actually takes a bit away from the game.
It's the sense of discovery that makes the game, and if you know everything in advance it devalues it in my opinion. I suppose it depends on whether you believe our ships have Star Trek type sensors that can interrogate and analyse the other ships or not. Personally I think not, and I prefer it that way.

Commander McLane wrote:

A general advice first:
Are you aware of the scripting documentation on the Wiki? Please take your time to ingest it (all of it, basically) and some of the general information on scripting, before you begin your project, and while you go along. Personally, when I'm OXPing, I have a lot of these Wiki documents opened and ready in over a dozen browser tabs for fast and easy referencing. I recommend this to all OXPers.

This is exactly what I do when I code. Tabs open everywhere.

1) Elite pilots are rare. There are not many of them in the whole Ooniverse, not more than some handfuls. And not all of them will be flying all the time. They're more the stuff of legends than something that an ordinary space farer actually sees. And if he does get lucky enough to fly alongside an Elite pilot, he'll be bragging about it in ZeroG-Bars for the rest of his life. Thus an encounter with an Elite pilot should be exceedingly rare.

They should be, as you state the system populator only populates ships with an accuracy from -5 to +5, even with skilled NPCs (thanks cim) set to highest level so pretty much everyone's accuracy is 10 there are only two base ships that would lead to Elite ratings. The Constrictor and the Viper Interceptor. For anyone else to be ranked Elite would rely on a 3rd party ship. My goal was for Elite pilots to occur rarely, generally only as goals of missions.

3) The Elite rating isn't advertised, and I assume most Elite pilots to fly "incognito" almost all of the time. Whether someone is "Dangerous" or "Elite" can't be determined from the outside, other than by the look of their ship. And that one can be deceptive. I'd be totally opposed to a mechanism that for instance displays a pilot's Elite rating next to the ship name.

4) Therefore I'm a little skeptical with regards to basing combat tactics on the opponent's Elite rating, because usually this rating won't be known to anyone else. A pirate group will attack a single worn-down Cobra III, and will only find out that the pilot was "Elite", because they'll all be dead or disabled after the fight. This is—I think—how it should be, and it's also realistic.

5) When binding the Elite rating to the accuracy property, there's the problem of how you determine your opponent's accuracy in the first place. Yes, I know that the NPC script can just look it up, but that's not realistic, that's an exploit. In-Ooniverse, only magic could tell you how accurate your opponent is, before you've actually fought him. You will only find out through observation during the fight how often your opponent misses and how well he hits. You can't know that beforehand, and NPCs shouldn't be able to, either.

6) The same goes for equipment. You can't look into your opponent's ship and determine which equipment he has installed, and NPCs shouldn't be able to, either.

I disagree. Every time you get a bounty from GalCop you have registered a kill, every time you attack a trader and have your legal status adjusted as a result a record is created. As the Wiki states the Galactic Federation maintains these records and assigns your threat rating based on these numbers. Sure there is plenty of wiggle room and I'm contemplating adding a random factor to account for mis-reporting, however if you have ever collected a bounty your status is absolutely advertised. I see the Threat Scanner upgrade as simply interrogating GalCop for that rating along with the legal status and potential bounty. Again I'm playing with including a random time factor between target acquisition and rating reporting to account for the time to pull the information from the GalCop database across a sub-space link.

Also don't mistake the mechanics of how the rating is determined with what the rating actually represents in game. The rating represents the number of known kills the NPC has achieved. I simply use accuracy and the upgrades a ship has to estimate what that might be. Again maybe a random factor is required.

Smivs wrote:

Just my two-pennies-worth.
I would be wary of falling into the Too Much Information trap. I personally would not want to know much about the ships around me, just as I don't want them knowing much about me. I sometimes find that even the STE telling me the legal status of other ships actually takes a bit away from the game.
It's the sense of discovery that makes the game, and if you know everything in advance it devalues it in my opinion. I suppose it depends on whether you believe our ships have Star Trek type sensors that can interrogate and analyse the other ships or not. Personally I think not, and I prefer it that way.

I understand. I was trying to find a way where there was still some gray area as to the actual facts behind the rating. Again my thought is that the ratings are an integral part of the fabric of the game and I'm interested in the thrill of seeing a potentially tough opponent. Of course the joy of OXPs is that you don't need to install what you don't want.

cim wrote:

Awarding and identifying equipment for an NPC is pretty straightforward. The trick is to get them to do something sensible based on it. Here's the state of the core equipment:

1. NPCs can use as if they were a player: Fuel, Missiles, Mines, Lasers, ECM systems, Escape pods, Fuel Injectors, Cloaking device, Large Cargo Bay*
2. NPCs can have this, but the effect is different from the player: shield boosters, military shield boosters
3. NPCs currently act as if they have this equipment whether it is installed or not. Actually adding it makes no difference: multi-targeting system, target system memory expansion, advanced space compass, external heat shielding**, docking computers
4. Installing this equipment to NPCs has no effect: extra energy unit, naval energy unit, advanced navigational array, scanner targeting enhancement, wormhole scanner, galactic hyperdrive, OXP equipment
5. NPCs cannot fit this equipment: passenger berths

* but in practice rather than fit the equipment this is done by giving the NPC a higher base capacity in shipdata.plist
** only some NPCs act as if they have this. It's still independent of the item.

Category 2 is because NPCs don't have shields, so these give extra energy and recharge rate instead.
Category 3 and 4 probably should be done properly, at least for most of them: suggestions on what NPCs should do with that equipment (or not do without it) are welcome.

OXP equipment is trickier - how do you explain to the AI what the properties of the equipment are and how they should affect its behaviour?

cim, thanks for this. It's those category 3 and 4 elements that I'd like to see if I can smooth over. The challenge I have is determining from the shipdata which ships include shields, extra energy units or naval energy units in the their max_energy and recharge_rates for the OXP idea I had. My idea is to have a system where all equipment is registered with the ship, even equipment right now has no effect on the game or a different effect to that it has on the players ship (for example an NPC with EQ_EXTRA_ENERGY_UNIT just indicates that the NPC has an extra energy unit pre-calculated into it's max_energy and recharge_rates and does not give any additional game effect). This would allow OXP writers to use those definitions for whatever they can imagine. I'm also guessing that most OXP equipment is dealt with within the framework of the existing ship event handlers. The only thing to look for is opportunities to expand the event handlers so that more situations can be exploited.

realbrit70 wrote:

I was trying to find a way where there was still some gray area as to the actual facts behind the rating. Again my thought is that the ratings are an integral part of the fabric of the game and I'm interested in the thrill of seeing a potentially tough opponent.

Absolutely. That's why I like a few 'tough opponent' OXPs in AddOns. I suppose I'd just rather find out the hard way - I like surprises, even nasty ones sometimes

realbrit70 wrote:

Every time you get a bounty from GalCop you have registered a kill, every time you attack a trader and have your legal status adjusted as a result a record is created. As the Wiki states the Galactic Federation maintains these records and assigns your threat rating based on these numbers. Sure there is plenty of wiggle room and I'm contemplating adding a random factor to account for mis-reporting, however if you have ever collected a bounty your status is absolutely advertised. I see the Threat Scanner upgrade as simply interrogating GalCop for that rating along with the legal status and potential bounty. Again I'm playing with including a random time factor between target acquisition and rating reporting to account for the time to pull the information from the GalCop database across a sub-space link.

Here I would disagree with you.. yes, GalCop keeps a record of your kills, but that is not the same thing as broadcasting ("advertised" as you put it) it to all and sundry.. To me, that is a personal thing between you and GalCop, and I no more see that database being open to anyone asking for it, than the government freely handing out personal information (such as your tax records) to any Tom, Dick or Harry who requests it. So far as I'm concerned, the transmission of kills, bounties received, etc, takes place over an encrypted channel.. not a wideband broadcast that's open to every eavesdropper in the system. Doing otherwise could have the unintended side effect of placing any number of commanders in potential danger.

realbrit70 wrote:

Again my thought is that the ratings are an integral part of the fabric of the game and I'm interested in the thrill of seeing a potentially tough opponent

You'll get that thrill if and when you take them on, anyway.. if combat ratings were openly available, you'd have the constant situation of wannabe's trying to 'cut a notch in their gunbelt' by picking fights with those with high ratings, in an attempt to boost their own reputation. A situation that plagued certain famous gunfighters in the Old West, forced to kill idiots who challenged them in an attempt to become famous.. That's precisely why I think GalCop would want to keep such things quiet, in an attempt to prevent things getting out of hand. If battles constantly broke out everywhere Elite combateers went, due to all the glory-seekers, they would soon be regarded as a major nuisance, not an asset in times of trouble.

realbrit70 wrote:

The challenge I have is determining from the shipdata which ships include shields, extra energy units or naval energy units in the their max_energy and recharge_rates for the OXP idea I had

I would probably assume - unless there's a player version to compare rates with - that anything with a recharge rate of 5 or above has an extra energy unit already fitted, and anything 10 or above has the naval version. (Or is a station or some other massive ship which has a recharge rate ridiculous by playable ship standards)

No NPCs currently have shields, of course (unless you install one of the relevant OXPs): mostly this is not compensated for by giving them more energy than the player variant.

Diziet Sma wrote:

If battles constantly broke out everywhere Elite combateers went, due to all the glory-seekers, they would soon be regarded as a major nuisance, not an asset in times of trouble.

I suspect that the Cooperative does largely (if privately) regard Elite combateers as a major nuisance. It's unlikely that most of them amassed their kill count in ways that the Cooperative would approve of, after all. That some of them may be hired - for extortionate rates, naturally - for the purposes of killing things the Cooperative really needs dead hardly compensates for the risk that someone else will do the same for something the Cooperative would rather have alive.

I don't know that I'd worry about glory-seekers so much, though: by the time the average commander has got to Mostly Harmless they will almost certainly have learnt the art of not picking fights they aren't absolutely sure they can win. The one exception might be the commander who gets to Elite not through great deeds of bravery in battle, but through not dying for a long time: I really should finish off the short piece of oofic I have about that case...

Diziet Sma wrote:

GalCop keeps a record of your kills...

Is it not the Elite Federation of Pilots that keeps track of a player's kills - GalCop would never condone such amoral ratings.

Cody wrote:

Diziet Sma wrote:

GalCop keeps a record of your kills...

Is it not the Elite Federation of Pilots that keeps track of a player's kills - GalCop would never condone such amoral ratings.

You are correct.. sorry.. sloppiness on my part.