Feature: consumable game logs and replays

[hooptie45]

There can be a wealth of knowledge derived from the game logs. Unfortunately it's not really in a form that is easily consumable. How much effort would it take to produce a log of all the game events as JSON? Also, would it be possible to have this log at both the client and server level?

My use case is applying this to machine learning, and using the past games as kind of a training set. But I'm sure there are other uses.

[JayDi85]

Current game log is useless. XMage show up only user friendly events, not all.

XMage have two different data source:

• Server side have game's states. GameState is full info about game at any moment -- that's what you need for AI;
• Client side have game's views. GameView is like game's state, but contain only current player's data to visualize -- it's useless for AI (well... it's can, but will be difficult like black box learning: you can't see inner game state like current active effects or variables).

[hooptie45]

Yeah I've poked around that GameState object from the debugger, I suspected that that was what I was looking for. If I recall correctly, we'd need to map the UUID references to the game's permanents, but that should be strait forward.

I'm kind of a newbie Java developer, but could we get a REST interface for the server that would would expose an endpoint to get all the current games being played, and an endpoint that for a given game UUID, return a json serialized version of the GameState?

And from the GameState, is it possible to know the details of each turn that was played up till that point? The entire GameState object might be overkill for this use case, just the basic information would be a great start.

[hooptie45]

To avoid constantly hammering the xmage server, I think dumping this data to a log file, or kafka stream might be something worth considering. I'd be happy it provide that, via something like a webhook; which the xmage server could ping after each state change(like after each player interaction) with a JSON payload of the current game state. If that was in place, I could build the API to expose the data.

[emerald000]

We shouldn't give access to GameState while a match is in progress. You could use it to see the opponent's hand and library.

[JayDi85]

You can't send GameState data to outside -- it's a cheat and users can't see full game data. It can be implemented by special server mode to process and save full game histories. Look at "testMode" as example.

GameStates object can contain history. It's uses for rollback to previous states (by user request or by ability action). Can be found in GameImpl.java.

By theory you can inject your code to void resume() or void play(UUID nextPlayerId) to save current state history, write json-logs or upstream data to outside (e.g. AI bot can access to that data at any time by API request).

Same code can be used to implement game's replay system (history of GameView objects).

[spjspj]

@emerald000 I was thinking about this (for a somewhat different reason). Implementing something similar to #3218 - but with extra information such as 'Player XYZ has priority' would be useful.

[hooptie45]

The more I think about it, dumping the GameState data to a file during the resume phase would be the way to go. Then we're not exposing anything to the outside during the game.

A similar hook can be added to the end game phase, which would flag that game log as ready for consumption. A separate worker process could be in charge of processing and cleaning up the finished game logs. The idea is to make this as lightweight as possible, so it doesn't effect the game servers performance.

Thoughts?

[jdsiddon]

So the logs would only available for processing after the game is over?

[hooptie45]

@jdsiddon That is correct. We'd be capturing the data as the game is in progress, but we'd defer releasing the data until after the game is finished.

[jdsiddon]

I think this would be a good idea.

[LevelX2]

I guess to create a JSON log on the client side would be possible and useful as AI data base also as a base to automatically analyse games. It would only inlude the data that the client can see. And it wouldn't burden the server.

Looking in the future and be aware that this would create a lot of work:
The best way in my opinion would be to replace the current views that way too often transfer the complete state information (from the client view) by a serial protocol (e.g. JSON format) that only transfers the changes compared to the last transfered data or the action a player did. That would probably enormously reduce the transfered data and help to solve the network problems. For sure the client has to be able to request a complete state (e.g. for reconnecting or if something gets out of order).

[JayDi85]

JSONL is good one for streaming and storage.

I like Russian Sberbank Holdem Challenge for AI last year with good docs and materials (but russian only). It's use JSON for data and streaming for poker game with AI -- game states, replays, streaming and AI. Same as XMage. You can find git repository here.

JSON streaming file example:
https://github.com/sberbank-ai/holdem-challenge/blob/master/simulator_stdin_example.jsonlines

[hooptie45]

@LevelX2 - regarding the client side Json logs, I think that would be a viable alternative; provided that we include a hook submit the this log back to a central service upon game completion; for mass analysis. I'd be happy to provide that service and expose the data for all who are interested. We might wanna make that opt
Regarding the Json driven client; this is something we should absolutely do! I'd really love to see a web based interface to replace the Java client; and there is alot of good frameworks to make this possible (graphql subscriptions, or websockets). If you provide the API; I'd be very interested in helping build out the web-ui; and the GraphQL server. This should probably be a separate issue, as it will be a substantial amount of work; but I'd like to get the conversation started.

[hooptie45]

@JayDi85 - that is a great find, and exactly what I was thinking we could do with xmage!

[JayDi85]

MTGA example (current open beta saved full game logs and input-output json-messages):

• income messages for users interactions (e.g. cards mouse hover), json example;
• income messages for different state changes (e.g. available actions, new items, animations and etc), json example 1, json example 2 with cards descriptions;
• it's contains only minimal info like action types and objects id (no descriptions, not dialogs, no texts);
• all messages have incremental numbers (one number = one game state changes).