Proper step-by-step guide for game creation

[Gnurro]

Currently the game creation documentation is fragmented between multiple files, The 'howto' also mixes more or less general descriptions of framework components with instructions. Docstrings inside the base clemgame code could be improved a lot. Specially the class hierarchy (ie GameResourceLocator->GameMaster) could be explained a lot better, making it clear which attributes and methods are established at each level in the hierarchy.
The closest is https://github.com/clp-research/clembench/blob/main/docs/howto_add_games_example.ipynb at the moment, but it refers to the less accessible other docs at the start. The order and the implementation examples are unintuitive for someone who does not already know the clemgame framework. Certain crucial information is delegated to side notes (for example the resource loading and use).

The existing documentation is not up to date with the current framework - specially after the split of the GameMaster classes for running from those for scoring the game.

A clear, step-by-step guide on how to set up all required methods, file structure and required files would help a lot with getting started properly.

[phisad]

As you noticed, these step-by-step guides become old very quickly. So I think there is no good way around the fact that people should "know the clemgame framework" before they can be productive with it. We can provide a class diagram to make dependencies more clear. But to see "which attributes and methods are established at each level in the hierarchy" the best way is still to look at the files in an IDE.

[davidschlangen]

Although taking an existing game and dissembling it would also be nice. Is there a game that a) doesn't have too much code and b) could count as a best practice example, for which a doc could be written that guides the learner through it?

[Gnurro]

As you noticed, these step-by-step guides become old very quickly. So I think there is no good way around the fact that people should "know the clemgame framework" before they can be productive with it. We can provide a class diagram to make dependencies more clear. But to see "which attributes and methods are established at each level in the hierarchy" the best way is still to look at the files in an IDE.

Good comments/docstrings in clemgame/clemgame.py would go a long way for this, specially for the GameMaster ABCs.

[phisad]

Although taking an existing game and dissembling it would also be nice. Is there a game that a) doesn't have too much code and b) could count as a best practice example, for which a doc could be written that guides the learner through it?

I think hellogame was supposed to do this, but I fear it is broken for now. And Brie wrote something for the private/shared game, didn't she?

[phisad]

As you noticed, these step-by-step guides become old very quickly. So I think there is no good way around the fact that people should "know the clemgame framework" before they can be productive with it. We can provide a class diagram to make dependencies more clear. But to see "which attributes and methods are established at each level in the hierarchy" the best way is still to look at the files in an IDE.

Good comments/docstrings in clemgame/clemgame.py would go a long way for this, specially for the GameMaster ABCs.

GameMaster only has setup() and play(). You mean DialogueGameMaster? Which is actually an implementation of the logic described in the paper (or at least a try to be as close to that as possible).

[Gnurro]

As you noticed, these step-by-step guides become old very quickly. So I think there is no good way around the fact that people should "know the clemgame framework" before they can be productive with it. We can provide a class diagram to make dependencies more clear. But to see "which attributes and methods are established at each level in the hierarchy" the best way is still to look at the files in an IDE.

Good comments/docstrings in clemgame/clemgame.py would go a long way for this, specially for the GameMaster ABCs.

GameMaster only has setup() and play(). You mean DialogueGameMaster? Which is actually an implementation of the logic described in the paper (or at least a try to be as close to that as possible).

I was referring to GameMaster and its child classes.

[davidschlangen]

@Gnurro , does the_annotated_hello_game.ipynb go some way towards doing what you wanted here?