Fractal Softworks Forum

Please login or register.

Login with username, password and session length
Advanced search  
Pages: [1] 2 3 ... 30

Author Topic: API request thread (please read OP before posting!)  (Read 170023 times)

LazyWizard

  • Global Moderator
  • Admiral
  • *****
  • Posts: 1327
    • View Profile
    • GitHub Profile
API request thread (please read OP before posting!)
« on: November 28, 2012, 08:52:12 AM »

Important notice: This is not a general suggestion thread. It is meant for requesting API hooks into existing features - in other words, access to things the game already keeps track of. If you want to suggest an entirely new feature, you should start a separate thread in the Suggestions sub-forum so your idea can be properly discussed without cluttering this thread.

You should also avoid overly broad requests. For example, posts like "give us access to NPC character creation" aren't very helpful. "Could we have a method createPerson() in FactoryAPI that returns a PersonAPI?", on the other hand, describes exactly what you're looking for.

There's a bit of gray area regarding the above, but as a general rule-of-thumb: if you can't reduce it down to a self-descriptive method signature, it's probably out of scope for this thread.


-----------------------

Outstanding Requests

This list should be current up to October 17, 2018.

LEGEND:
  • Outstanding request
  • Added within the most recent release cycle (0.8.1a)
  • Confirmed to be added to the next release in some form source

If your suggestion in this thread is missing from this list, feel free to PM me. It's possible that I didn't add it because it failed the above guidelines, was previously rejected, or already exists in the API in some form; but it's more likely that I just didn't see it. Sorry about that! :)


Combat

com.fs.starfarer.api.combat.ArmorGridAPI:
  • Vector2f getLocation(int cellX, int cellY)

com.fs.starfarer.api.combat.CombatEngineAPI:
  • boolean isSideDefeated(FleetSide side)

com.fs.starfarer.api.combat.DamagingProjectileAPI:
  • SpriteAPI getSprite()
  • setHitPoints(float amount)
  • float getMoveSpeed()

com.fs.starfarer.api.combat.WeaponAPI$DerivedWeaponStatsAPI:
  • float getBurstEmp()
  • float getEmpOver30Sec()

com.fs.starfarer.api.combat.EveryFrameCombatPlugin:
  • combatEntityPreDamaged(CombatEntityAPI entity, DamageAPI damage, WeaponAPI weapon, DamagingProjectileAPI proj)
  • combatEntityPreDamaged(CombatEntityAPI entity, DamageAPI damage, WeaponAPI weapon, BeamAPI beam)
  • combatEntityDamaged(CombatEntityAPI entity, DamageAPI damage, WeaponAPI weapon, DamagingProjectileAPI proj)
  • combatEntityDamaged(CombatEntityAPI entity, DamageAPI damage, WeaponAPI weapon, BeamAPI beam)

com.fs.starfarer.api.combat.HullModEffect:
  • onRemoval(ShipAPI ship)

com.fs.starfarer.api.combat.MissileAPI:
  • boolean isMIRV()
  • boolean hasMIRVed()

com.fs.starfarer.api.combat.MutableShipStatsAPI:
  • getBallisticAmmoRegenBonus()
  • getEnergyAmmoRegenBonus()
  • getMissileAmmoRegenBonus()
  • getObjectiveCaptureTimeMod()

com.fs.starfarer.api.combat.ShieldAPI:
  • setCollisionClass(CollisionClass collisionClass)
  • getCollisionClass()
  • setCenter(Vector2f center)

com.fs.starfarer.api.combat.ShipAPI:
  • setHullStyleId(String hullStyleId)
  • syncWithArmorGridState()
  • syncWeaponDecalsWithArmorDamage()

com.fs.starfarer.api.combat.ShipSystemAPI:
  • float getRange()

com.fs.starfarer.api.combat.ShipEngineControllerAPI$ShipEngineAPI:
  • float getDisabledTime()
  • setDisabledTime(float time)
  • setStyleID(string styleId)
  • setEngineColor(Color color)
  • setContrailParticleSizeMult(float mult)
  • setContrailParticleDuration(float duration)
  • setContrailParticleFinalSizeMult(float mult)
  • setContrailMaxSpeedMult(float mult)
  • setContrailAngularVelocityMult(float mult)
  • setContrailWidth(float width)
  • setContrailColor(Color color)
  • enum EngineType (GLOW, SMOKE)
  • setType(EngineType type)
  • setEngineFlameSprite(SpriteAPI sprite)
  • setEngineGlowSprite(SpriteAPI sprite)
  • setEngineGlowSecondarySprite(SpriteAPI sprite)
  • setContrailParticleSprite(SpriteAPI sprite)
  • float getContrailParticleSizeMult()
  • float getContrailParticleDuration()
  • float getContrailParticleFinalSizeMult()
  • float getContrailMaxSpeedMult()
  • float getContrailAngularVelocityMult()
  • float getContrailWidth()
  • enable()
  • EngineType getType()
  • setLocation(Vector2f newLoc)

com.fs.starfarer.api.combat.ShipSystemAPI:
  • setCooldownRemaining(float cooldown)
  • setCooldownMax(float maxCooldown)

com.fs.starfarer.api.combat.WeaponAPI:
  • AutofireAIPlugin getAutofireAIPlugin()
  • setAutofireAIPlugin(AutofireAIPlugin plugin)
  • boolean isAutofire()
  • setCurrHealth(float health)
  • Color getGlowColor()
  • setGlowColor(Color color)
  • BarrelMode getBarrelMode()
  • MuzzleFlashAPI getMuzzleFlash()
  • WeaponGlowJitterAPI getWeaponJitter()
  • setTurnRate(float turnRate)
  • setFluxToFire(float flux)
  • boolean isInterruptibleBurst()
  • interruptWeapon()
  • setLocation(Vector2f newLoc)

com.fs.starfarer.api.loading.WeaponSpecAPI:
  • String getSpriteName()
  • String getProjectileSpec()


Campaign

com.fs.starfarer.api.campaign.FactionAPI:
  • setDisplayName(String name)
  • setColor(Color color)

com.fs.starfarer.api.fleet.FleetMemberStatusAPI:
  • float getHullFraction(int index)


Misc

com.fs.starfarer.api.SettingsAPI:
  • boolean fileExists(String filename)


Requested Classes

com.fs.starfarer.api.combat.MuzzleFlashAPI:
  • float getLength()
  • float getSpread()
  • float getParticleSizeMin()
  • float getParticleSizeRange()
  • float getParticleDuration()
  • int getParticleCount()
  • Color getParticleColor()
  • setLength(float length)
  • setSpread(float spread)
  • setParticleSizeMin(float min)
  • setParticleSizeRange(float range)
  • setParticleDuration(float duration)
  • setParticleCount(int count)
  • setParticleColor(Color color)

com.fs.starfarer.api.combat.WeaponGlowJitterAPI:
  • setDuration(float duration)
  • float getDuration()
  • float setJitterX(float jitter)
  • float getJitterX()
  • float setJitterY(float jitter)
  • float getJitterY()
« Last Edit: October 17, 2018, 02:39:19 AM by LazyWizard »
Logged

xenoargh

  • Admiral
  • *****
  • Posts: 4882
  • naively breaking things!
    • View Profile
Re: API request
« Reply #1 on: November 28, 2012, 09:14:39 AM »

It'd also be nice to have:

WeaponAPI
string getWeaponName() - not the display name, but the internal name, since display names can be the same but internal names must be unique.

FleetSide
Does not have a NEUTRAL and HOSTILE designation;  it'd be nice to have, so that we can spawn NEUTRAL objects (not attacked by anybody, doesn't attack anybody) and HOSTILE objects (attacks and is attacked by everybody).  This would provide for a .junk alternative and allow for gameplay stuff.

SectorAPI
boolean isBattleOccurring(true)
List currentBattles(for each entry, fleet1.id, fleet2.id)
callback BattleEnded(fleet1.id,fleet2.id,faction1.id,faction2.id,winnerfaction.id)

Basically, stuff for keeping a better eye on what's happening throughout the System, which right now is a bit of a pain.

Lastly, it'd be nice to have a script that runs when entering a Station; then we could implement profitable trading relatively easily.

« Last Edit: November 28, 2012, 09:27:38 AM by xenoargh »
Logged
Please check out my SS projects :)
Xeno's Mod Pack

Alex

  • Administrator
  • Admiral
  • *****
  • Posts: 17414
    • View Profile
Re: API request
« Reply #2 on: November 28, 2012, 09:16:15 AM »

MutableShipStatsAPI
  • ShipAPI getOwner()

Curious - where are you getting a MutableShipStatsAPI that you don't also have access to the ShipAPI? There may be a good reason for that.

ShipAPI
  • ShipAPI getTarget() (or a way to get the currently selected target outside of ShipSystemAIScript's advance())
ShipVariantAPI
  • String getVariantName()
WeaponAPI
  • float getBaseDamage()
  • boolean isDisabled()
  • float getDisabledDuration()

Added, except for getBaseDamage(), which is actually quite a pain. Hmm. Looks like the variant API could use a lot more attention, too. I'll note both of these down for later. Thanks for making the suggestions, I really appreciate it.
Logged

Alex

  • Administrator
  • Admiral
  • *****
  • Posts: 17414
    • View Profile
Re: API request
« Reply #3 on: November 28, 2012, 09:25:16 AM »

It'd also be nice to have:

WeaponAPI
string getWeaponName() - not the display name, but the internal name, since display names can be the same but internal names must be unique.

There's WeaponAPI.getId() which does exactly that.

FleetSide
Does not have a NEUTRAL and HOSTILE designation;  it'd be nice to have, so that we can spawn NEUTRAL objects (not attacked by anybody, doesn't attack anybody) and HOSTILE objects (attacks and is attacked by everybody).  This would provide for a .junk alternative and allow for gameplay stuff.

SectorAPI
isBattleOccurring(true,fleet1.id,fleet2.id)
BattleEnded(fleet1.id,fleet2.id,faction1.id,faction2.id,winnerfaction.id)

Both would allow for a lot more context-sensitive battlefield control.

Lastly, it'd be nice to have a script that runs when entering a Station; then we could implement profitable trading relatively easily.

Ah yes, asking for features under the guise of API additions. I see what you did there :) Btw, where you see the "owner" id as an int (rather than a FleetSide), 0 is player, 1 is enemy, and 100 is neutral. Though setting a ship to neutral would make it fire on everyone, I think.

Added CombatEntityAPI.setOwner(int owner) - that should take care of spawning neutral stuff, I think.
Logged

LazyWizard

  • Global Moderator
  • Admiral
  • *****
  • Posts: 1327
    • View Profile
    • GitHub Profile
Re: API request
« Reply #4 on: November 28, 2012, 09:32:23 AM »

MutableShipStatsAPI
  • ShipAPI getOwner()

Curious - where are you getting a MutableShipStatsAPI that you don't also have access to the ShipAPI? There may be a good reason for that.

ShipSystemStatsScript.

Added, except for getBaseDamage(), which is actually quite a pain. Hmm. Looks like the variant API could use a lot more attention, too. I'll note both of these down for later. Thanks for making the suggestions, I really appreciate it.

Thank you for adding those in. Hmm, is the problem with getBaseDamage() due to the MutableStats? If so, would a getDamage() method suffer the same difficulties? Sorry to bother you about this, but I'm trying to write helper classes that calculate the threat generated by nearby enemies, and damage is fairly important to the equation. ;)

And thank you for putting in so much effort on the modding side of things. I've been modding for 12 years, and Starfarer is (by far!) the most enjoyable of all the games I've ever modded. :)

Oh, and if you're noting things that need attention, ShipAPI's getPhaseCloak() still returns a placeholder Object. ;)
Logged

xenoargh

  • Admiral
  • *****
  • Posts: 4882
  • naively breaking things!
    • View Profile
Re: API request
« Reply #5 on: November 28, 2012, 09:44:09 AM »

Quote
There's WeaponAPI.getId() which does exactly that.
Oops, thought that returned something else, guess I didn't have enough coffee this morning...

Quote
Btw, where you see the "owner" id as an int (rather than a FleetSide), 0 is player, 1 is enemy, and 100 is neutral. Though setting a ship to neutral would make it fire on everyone, I think.

Added CombatEntityAPI.setOwner(int owner) - that should take care of spawning neutral stuff, I think.
Aha.  Well, I guess that takes care of spawning neutral, unarmed "ships" that are actually just playing the role of space junk, yay!  Now I just have to make the art assets and write the code, cool!

I hope that the "can I fire at this" team-check's all in one place; it should be straightforward to do "not my team, but not team 100" to keep AI from shooting NEUTRAL stuff and "team 100 does not fire".  Request that team 666 be designated HOSTILE, lol.

Quote
Ah yes, asking for features under the guise of API additions. I see what you did there :)
Well, maybe, lol.  

I want to be able to see stuff that's going on in the strategic map a little less clunkily.  My diplomatic system, for example, just goes off of changes over time and is potentially exploitable (for example, you can attack X, drop Relations .1, then attack Y and Z before the next update and avoid the "you just attacked an ally" condition I wrote).  Having a callback when a battle ends on the strategic map would be a huge benefit there, as well as allowing for a bunch of other stuff to be made possible such as writing some basic strategic-level AI.  Right now it's very clunky getting information about what's going on, but it's gotta be there already, because the engine's clearly acting on it.


Oh and on getDamage(), I'd rather just see the current true damage; that's very complex because of flux bonuses, character bonuses, system bonuses, bonuses for your bonuses, etc.
« Last Edit: November 28, 2012, 09:45:42 AM by xenoargh »
Logged
Please check out my SS projects :)
Xeno's Mod Pack

Alex

  • Administrator
  • Admiral
  • *****
  • Posts: 17414
    • View Profile
Re: API request
« Reply #6 on: November 28, 2012, 10:25:23 AM »

ShipSystemStatsScript.

Added CombatEntityAPI MutableShipStatsAPI.getEntity(). You can cast it to ShipAPI in that particular case (sometimes, it may be a MissileAPI).

And thank you for putting in so much effort on the modding side of things. I've been modding for 12 years, and Starfarer is (by far!) the most enjoyable of all the games I've ever modded. :)

Thank you, it's my pleasure :)

Oh, and if you're noting things that need attention, ShipAPI's getPhaseCloak() still returns a placeholder Object. ;)

Changed to ShipSystemAPI. That's what it already returned, just hadn't changed the method signature.

Hmm, is the problem with getBaseDamage() due to the MutableStats? If so, would a getDamage() method suffer the same difficulties? Sorry to bother you about this, but I'm trying to write helper classes that calculate the threat generated by nearby enemies, and damage is fairly important to the equation. ;)
Oh and on getDamage(), I'd rather just see the current true damage; that's very complex because of flux bonuses, character bonuses, system bonuses, bonuses for your bonuses, etc.

Yeah, that's part of the problem. But all that doesn't get figured out until a projectile is actually created. Which you can get access to once they're flying, which can be a bit late for certain things.

Added WeaponAPI.isFiring(), btw. That may come in handy for determining how much of a threat something is.

Let me just expose something that's used internally. It's not taking skills or damage bonuses into account, but are the baseline weapon stats, in a more immediately useful form:

Code
public static interface DerivedWeaponStatsAPI {
float getBurstFireDuration();
float getSustainedDps();
float getEmpPerSecond();
float getDamageOver30Sec();
float getDps();
float getBurstDamage();
float getFluxPerDam();
float getRoF();
float getFluxPerSecond();
float getSustainedFluxPerSecond();
}
.

Also added WeaponAPI.getDerivedStats().


I hope that the "can I fire at this" team-check's all in one place; it should be straightforward to do "not my team, but not team 100" to keep AI from shooting NEUTRAL stuff and "team 100 does not fire".  Request that team 666 be designated HOSTILE, lol.

It's not, actually. Which could pose a bit of a problem :)

I want to be able to see stuff that's going on in the strategic map a little less clunkily.  My diplomatic system, for example, just goes off of changes over time and is potentially exploitable (for example, you can attack X, drop Relations .1, then attack Y and Z before the next update and avoid the "you just attacked an ally" condition I wrote).  Having a callback when a battle ends on the strategic map would be a huge benefit there, as well as allowing for a bunch of other stuff to be made possible such as writing some basic strategic-level AI.  Right now it's very clunky getting information about what's going on, but it's gotta be there already, because the engine's clearly acting on it.

Yeah, I understand. I just don't want to go expanding the campaign API until a few versions from now.


Now then, I should really go back to working on some design docs - been doing nothing but posting here since this morning. Well, and fixing/adding things in response, so I guess that counts as "real work" :)
Logged

xenoargh

  • Admiral
  • *****
  • Posts: 4882
  • naively breaking things!
    • View Profile
Re: API request
« Reply #7 on: November 28, 2012, 10:41:11 AM »

Quote
Yeah, I understand. I just don't want to go expanding the campaign API until a few versions from now.
NP, I'm sure I can keep myself occupied until then :) Just would get rid of a lot of hassles and provide a good way to make a lot of stuff possible-if-ugly until the Shiny Version is available.
Logged
Please check out my SS projects :)
Xeno's Mod Pack

LazyWizard

  • Global Moderator
  • Admiral
  • *****
  • Posts: 1327
    • View Profile
    • GitHub Profile
Re: API request
« Reply #8 on: November 29, 2012, 08:58:46 AM »

Ran into a few more:

ShipAPI:
  • float getTurnVelocity()
  • getTurnDirection()

WeaponAPI:
  • ShipAPI getWielder()

enum DefenseType (HULL, ARMOR, SHIELD, PHASE)
Logged

Alex

  • Administrator
  • Admiral
  • *****
  • Posts: 17414
    • View Profile
Re: API request
« Reply #9 on: November 29, 2012, 09:34:29 AM »

Added:
WeaponAPI.getShip()
CombatEntityAPI.getAngularVelocity() (you can use the sign to figure out the direction - follows convention, ccw is positive)


enum DefenseType (HULL, ARMOR, SHIELD, PHASE)

Huh? :)
Logged

LazyWizard

  • Global Moderator
  • Admiral
  • *****
  • Posts: 1327
    • View Profile
    • GitHub Profile
Re: API request
« Reply #10 on: November 29, 2012, 09:38:51 AM »

enum DefenseType (HULL, ARMOR, SHIELD, PHASE)

Huh? :)

I noticed we have one for DamageType. I'm writing a library to help modders with combat AI, and I didn't want to force them to use any 'unofficial' additions to the API. ;)

But yeah, sorry, that was kind of random.
Logged

Alex

  • Administrator
  • Admiral
  • *****
  • Posts: 17414
    • View Profile
Re: API request
« Reply #11 on: November 29, 2012, 09:41:25 AM »

Well, no, what I meant was "why/where/what" etc - since there's nothing like that in the core game code :)
Logged

LazyWizard

  • Global Moderator
  • Admiral
  • *****
  • Posts: 1327
    • View Profile
    • GitHub Profile
Re: API request
« Reply #12 on: November 29, 2012, 09:48:02 AM »

I know, I was just asking for a standardized way for our code to refer to the various defense types. But I know how you feel about adding things that will only be used by mods. ;)
Logged

Alex

  • Administrator
  • Admiral
  • *****
  • Posts: 17414
    • View Profile
Re: API request
« Reply #13 on: November 29, 2012, 10:00:24 AM »

Well, you can add that in your library, right? Since your request for a new enum didn't come accompanied with API methods that would actually use it... :)

Heheh, this is turning into a very confusing conversation. Yay for talking past each other.
Logged

Sproginator

  • Admiral
  • *****
  • Posts: 3592
  • Forum Ancient
    • View Profile
Re: API request
« Reply #14 on: November 29, 2012, 10:10:33 AM »

Lazy, it seems you are a very helpful member of the community In regards to advanced modding, why not do some tutorials?
Logged
A person who's never made a mistake, never tried anything new
- Albert Einstein

As long as we don't quit, we haven't failed
- Jamie Fristrom (Programmer for Spiderman2 & Lead Developer for Energy Hook)
Pages: [1] 2 3 ... 30