3. Draft: Power Creeps API

Draft: Power Creeps API

  • Dev Team

    Here is the request for comments proposal of the Power Creeps API.

    PowerCreep.create(name, className)

    A static method.

    Create a new level 0 power creep. The created power creep isn't spawned in the world yet, it's just added to your account. In order to spawn it, you have to call PowerSpawn.spawnPowerCreep. You must have 1 spare Power Level in your account, othwerise ERR_NOT_ENOUGH_RESOURCES is returned.

    Example:

    PowerCreep.create('MyOperator1', CLASS_OPERATOR);

    Game.powerCreeps['MyOperator1'] will be added on the next tick.

    PowerCreep.prototype

    Inherited from RoomObject.

    Own properties:

    • name string
    • className string
    • hits number
    • hitsMax number
    • carry object
    • carryCapacity number
    • owner object
    • level number
    • spawnCooldown number - the number of ticks to wait until the creep can be spawned in the world, or undefined if it is already spawned;
    • powers object<string, object> - list of all creep's powers in the following format:
      { 
  [PWR_OPERATE_EXTENSION]: {
    level: 1,
    cooldown: 0
  },
  [PWR_OPERATE_SPAWN]: {
    level: 2,
    cooldown: 3  // ticks until you can use it again
  }
}

    PowerCreep.prototype.upgrade(power)

    Level up the power creep by upgrading one of its powers. power can by any of PWR_* constant. You need to have 1 spare Power Level in your account, otherwise ERR_NOT_ENOUGH_RESOURCES is returned. If the specified power cannot be taken on this level, ERR_INVALID_ARGS is returned.

    Example:

    Game.powerCreeps['MyOperator1'].upgrade(PWR_OPERATE_EXTENSION);

    PowerCreep.prototype.delete()

    Remove this power creep from your account, releasing the Power Levels it uses. The creep must not be spawned in the world in order to call this method.

    Example:

    Game.powerCreeps['MyOperator1'].delete();

    PowerCreep.prototype.usePower(power, [target])

    Use the specified power. power is one of the PWR_* constants. target (optional) can be any RoomObject or RoomPosition instance depending on the power semantics. If the power is not available for this creep, ERR_NO_BODYPART is returned. If the power's cooldown is still active, ERR_TIRED is returned. If power usage is not enabled in the room (room.controller.isPowerEnabled === false), ERR_INVALID_ARGS is returned.

    Example:

    Game.powerCreeps['MyOperator'].usePower(PWR_EXTEND_SOURCE, source);

    PowerCreep.prototype.enableRoom(controller)

    Enable power usage in the room. The controller has to be at the adjacent square.

    Example:

    let powerCreep = Game.powerCreeps['MyOperator1'];
powerCreep.enableRoom(powerCreep.controller);

    PowerSpawn.prototype.spawnPowerCreep(name)

    Spawn the power creep with the specified name. The creep must be not spawned already and have spawnCooldown === 0. The creep is spawned immediately on the next tick.

    Example:

    powerSpawn.spawnPowerCreep('MyOperator1');

    RoomObject.prototype.effects

    The list of active temporary effects (e.g. applied powers) on this object in the following format:

    console.log(Game.spawns['Spawn1'].effects);

{
  [PWR_OPERATE_SPAWN]: {
    level: 2,
    ticksRemaining: 942
  }
}

    StructureController.prototype.isPowerEnabled

    A boolean value indicating whether power usage is enabled in this room.


  • Looks good! Should delete be suicide to match with regular creeps?

    Will power spawns also need a Spawning object and/or directions?

    1 Reply
  • Dev Team

    @tigga

    Looks good! Should delete be suicide to match with regular creeps?

    suicide is when the creep is killed and becomes not spawned in the world, but still exists and occupies Power Levels. delete is when it is totally removed from your account.

    Will power spawns also need a Spawning object and/or?

    No, due to this: The creep is spawned immediately on the next tick.


  • PowerSpawn.prototype.spawnPowerCreep(name)

    Should this have a directions property? It would be great to not spawn my power creeps outside of ramparts if I have a power spawn on the edge of a defended line.

    Since I don't see any "can spawn" functions, are we to assume that power creeps are free to spawn if they are off cooldown? 😢

    PowerCreep.prototype.delete()
    The creep must not be spawned in the world in order to call this method.

    Why does this require the power creep be spawned? So, if while testing I create a power creep, and then I want to delete it, I have to spawn it first?

    Otherwise this looks great!

    1 Reply
  • Dev Team

    @gankdalf

    Should this have a directions property? It would be great to not spawn my power creeps outside of ramparts if I have a power spawn on the edge of a defended line.

    We'll consider it.

    Since I don't see any "can spawn" functions, are we to assume that power creeps are free to spawn if they are off cooldown?

    Yes, they are free to spawn.

    Why does this require the power creep be spawned?

    You misread, it requires the creep to be NOT spawned.

    😬
    1 Reply

  • You misread, it requires the creep to be NOT spawned.

    That makes so much more sense.


  • Will there be anything like the following:

    Game.map.isPowerEnabled(roomName)?

    Room.prototype.powerEnabled?

    It would be good to make sure that every possible information gathering feature is added for anything related to all of this. Want to avoid informational gaps similar to the lack of a way to know which rooms on the map are blocked by novice/respawn zones or not.

    2 Replies

  • @helam Also, given that power creeps are essentially defenseless in non-power enabled rooms, it would be very useful to be able to avoid pathing through those rooms.

  • Dev Team

    @helam No, the power enabled flag is available only for objects loaded from the database (i.e. visible rooms). You may want to observe them yourself periodically and cache this info. It's not like novice/respawn areas, since you do have the way to check it, you just need to obtain visibility.

    1 Reply

  • @artch so Room objects will have a property to tell us if power is enabled or not? If we can observe it this is good.

    1 Reply
  • Dev Team

    @helam It's Room.controller.isPowerEnabled, see the first post here:

    StructureController.prototype.isPowerEnabled

    A boolean value indicating whether power usage is enabled in this room.

    1 Reply

  • @artch O.o I must have missed that, sorry and thank you. Has it been decided how to handle power in rooms without controllers? In this post (https://screeps.com/forum/topic/2183/power-creeps-update/19) it was mentioned that it had not been decided yet.

    1 Reply

  • Will there a method to get all available (created in account) power creeps? Something like Game.powerCreeps or PowerCreep.getCreeps(). Will they also occured in Game.creeps? If yes then only if spawned or when unspawned too? Also maybe there must by a property spawned in any case.

    1 Reply
  • Dev Team

    @u-238

    Will there a method to get all available (created in account) power creeps? Something like Game.powerCreeps or PowerCreep.getCreeps().

    I think that examples in the first post answer your question. It's Game.powerCreeps.

    Also maybe there must by a property spawned in any case.

    spawnCooldown property serves this purpose:

    the number of ticks to wait until the creep can be spawned in the world, or undefined if it is already spawned;


  • @helam @artch

    If power creeps work in rooms without controllers, please consider adding a isPowerEnabled property on the room instead of on the controller.

    Also please consider making a better way for me to tell if one of my rooms is being attacked with a power apart from periodically cycling through every single roomObject in every single room I own to check if there is an entry in .effects that I don't expect to be there. For hostile effects, it would be amazing if you told me which player owns the effect.

    For instance, maybe there could be a Room.activeEffects property that is an array of all the effects active in a room. Even better would be if it were a hashmap to a list of effects indexed by owner. So Room.activeEffects['shedletsky'] will give me an array of all my active effects.

    1 Reply
  • Dev Team

    @shedletsky I think that adding power events to the room events log will be more correct approach.

    1 Reply

  • @artch Yes, I didn't know about the room event log when I posted. I think adding the owner/creator as a property on each effect in the log would be helpful, otherwise figuring out when I'm being messed with could be challenging.