Draft: room event log

[artch]

Currently Screeps has no API to track what actions have been succesfully performed, or what creeps have made certain actions to which targets. This is especially important in battles, when your creep receives damage, you can't determine the actual attacker. This draft proposes new system called room event log. We'd like to hear your feedback on this API and whether it fits your needs.

New property is proposed: Room.eventLog. It is an array containing event items that describe most actions that have taken place in this room on the last tick:

[{
  type: EVENT_ATTACK,
  objectId: '54bff72ab32a10f73a57d017',
  data: {
    targetId: '54bff74fb32a10f73a57d018',
    attackType: 'attack',  // attack | rangedAttack | rangedMassAttack | dismantle | nuke
    damage: 20
  }
},
{
  type: EVENT_HEAL,
  objectId: '54bff72ab32a10f73a57d017',
  data: {
    targetId: '54bff72ab32a10f73a57d017',
    healed: 10
  }
},
{
  type: EVENT_HARVEST,
  objectId: '54bff72ab32a10f73a57d017',
  data: {
    targetId: '54bff74fb32a10f73a57d018',
    harvested: 50
  }
},
{
  type: EVENT_REPAIR,
  objectId: '54bff72ab32a10f73a57d017',
  data: {
    targetId: '54bff74fb32a10f73a57d018',
    repaired: 1000,
    energySpent: 10
  }
},
{
  type: EVENT_UPGRADE_CONTROLLER,
  objectId: '54bff72ab32a10f73a57d017',
  data: {
    targetId: '54bff74fb32a10f73a57d018',
    upgraded: 10,
    energySpent: 5
  }
},
{
  type: EVENT_TRANSFER,
  objectId: '54bff72ab32a10f73a57d017',
  data: {
    targetId: '54bff74fb32a10f73a57d018',
    resourceType: RESOURCE_ENERGY,
    amount: 200
  }
}]

Events last only one tick, so if you need to track event logs for a longer period, you have to store them on your own. Every room has its own Room.eventLog array. You can track events performed by a particular creep like this:

_.filter(creep.room.actionLog, {objectId: creep.id});

Or you can find all hostile actions against your creeps and structures:

_.forEach(Game.rooms, room => {
  let attackEvents = _.filter(room.eventLog, {type: EVENT_ATTACK});
  attackEvents.forEach(event => {
    let target = Game.getObjectById(event.targetId);
    if(target && target.my) {
      console.log(event);
    }
  });
});

Even when the creep object is gone (being killed or leaving the room), the attacking event is still recorded to the log, so you are able to reason on what's happened.

Not only hostile actions are recorded, but you can also use the events log to track effectiveness of your harvest, upgrade and repair operations.

Since these JSON arrays can become quite big, they are stored and fetched by the engine as raw strings, and deserialized using JSON.parse when you access the Room.eventLog property for the first time similar to Memory parsing. Thus, if you opt-in to use this feature, it will incur some CPU cost depending on the number of actions in this particular room in the given tick.

[Toolmaker]

Great idea, however, since accessing the eventLog incurs costs, would it be possible to apply filtering before accessing the eventlog? For instance, let's assume I do not care about my harvest effeciency but only care for attack events, would it be possible to call setEventLogFilter() on the room and only supply EVENT_ATTACK as a filter?

By default, no filtering is applied, but after calling this method, all other events are ommitted from the log(and thus also save cpu cycles server side when serializing it).

[Tigga]

There's no EVENT_MOVE in the example, is that also going to be an event? I'd also be interested in seeing what rangedMassAttack looks like.

Parse times seem like they should be small. I'd guess <0.1 CPU for most late game rooms.

[artch]

@toolmaker No, it's not possible, otherwise we would need to duplicate filtered data in the backend.

[artch]

@tigga move action is not recorded (I don't see any reason why it should be, it's just a waste of resources). rangedMassAttack is recorded as multiple events for each affected target.

[eduter]

I think, ideally, any intent that may fail even after getting an OK, would be logged, so there's a straightforward way to check for success/failure/partial success. That would include move intents. To me, detecting collisions is about the same as checking for a failed/partial transfer, it's possible without event logs, but it's cumbersome.

[artch]

@eduter We wouldn't be able to maintain such amount of internal network traffic in our cluster. Also, it would increase CPU parsing cost for players as well.

[Tigga]

I'm fine with no move, just checking. It'd be useful, but it's trackable except when they move to an exit tile (maybe EVENT_EXIT?), so that's fine.

RMA is going to create a lot of events, but I guess it's rare so that's not going to be much of CPU hit in general.

[artch]

@tigga EVENT_EXIT looks interesting, we have to consider that.

[Gankdalf]

It might also be useful to have an EVENT_ENTER instead of having to search every creep in the room for hostiles

[SteveTrov]

Looks awesome, I like the idea of EVENT_ENTER & EVENT_EXIT.

The only other event I can think of is EVENT_DIE, but this maybe covered by the new tombstone functionality.

[Kamots]

How about EVENT_DESTROY? There is currently no easy way to see when a structure is destroyed except for storing all structures in Memory and comparing on a regular basis. It would be triggered on the use of destroy() or when the structure hitpoints reach zero. I think that would be very useful.

[artch]

@kamots What is the use case here? How do you check what structure is destroyed without storing it in Memory? We'd need to duplicate some structure info in the event data, which is not very optimal.

[SteveTrov]

My use case for this would be to be able to do something specific when a structure is destroyed, such as trigger safe mode or add a new construction site to replace the destroyed structure.

I would be happy to have a flag in EVENT_ATTACK to say whether or not the object was destroyed by the attack.

[artch]

@stevetrov I mean, how do you get rid of storing and comparing in Memory, if you only have targetId in the event data, and Game.getObjectById(targetId) === null?

[SteveTrov]

@artch said in Draft: room event log:

@stevetrov I mean, how do you get rid of storing and comparing in Memory, if you only have targetId in the event data, and Game.getObjectById(targetId) === null?

The difference with server side code is that it is already processing the intents that caused the damage.

Although thinking about it, IIRC destruction is not determined at the time damage is applied, its determined after the heal is applied. So an object EVENT_DESTROY would make more sense.

Is there a reason you cant create the EVENT_DESTORY object at the same time that you detect the creep / structure is dead server side?

[artch]

@stevetrov You don't seem to get the point. I don't mean server-side logic, it's trivial. My point is that this event would look like this:

{
  type: EVENT_DESTROYED,
  objectId: '54bff72ab32a10f73a57d017'
}

You have to store your structures info in Memory in order to do something useful with this objectId. But if you're storing your structures in memory already, it's trivial to check Game.structures[id], and it's easier than looking for EVENT_DESTROYED events every tick.

[SteveTrov]

@artch said in Draft: room event log:

Ah i c your point now

How about:

{ type: EVENT_STRUCTURE_DESTROYED, objectId: '54bff72ab32a10f73a57d017' structureType: STRUCTURE_RAMPART, pos: { x :23, y: 35, roomName: "E1N1" } }

And for creeps we could have

{ type: EVENT_CREEP_DESTROYED, name: "MyAwesomeCreep", deathReason: <oldAge|suicide|murdered> }

The later would provide an alternative to comparing Game.creeps & Memory.creeps every tick.

[artch]

Keep in mind events are not user-specific, they are exposed to all users with an access to the given room in exactly the same form, so you cannot distinguish your creeps/structures from another player's this way. And we cannot add username property here for technical reasons.

[ags131]

@stevetrov EVENT_CREEP_DESTROYED is already easy, tombstones already provide that information.