Merge remote-tracking branch 'origin/dev' into dev

CHANGELOG.md

@@ -20,6 +20,7 @@
 - Get image size now returns an already transposed array (opencv style - not pygame style)
 - Deterministic Order Generation, opt-in. Instead of random you can define a list of orders that will be generated
 - thumbnails of layouts in pygame 2d debug modus 
+- Sequence Diagrams for understanding internal execution flow.
 
 ### Changed
 - Available orders are sorted now (always the same order for the recipe graphs)

cooperative_cuisine/player.py

@@ -168,7 +168,7 @@ class Player:
             self.holding = counter.drop_off(self.holding, player=self.name)
 
         elif not isinstance(
-            counter.occupied_by, (list, deque)
+            counter.occupied_by, (list, deque)  # TODO sure ?
         ) and self.holding.can_combine(counter.occupied_by):
             returned_by_counter = counter.pick_up(on_hands=False, player=self.name, player_holding=self.holding)
             self.holding.combine(returned_by_counter)

docs/README.md

+## Additional Documentation
+
+The main documentation is done vie pdoc. It extracts the doc strings from the library and creates a running website via gitlab pages.
+You can find it here: [Documentation](https://scs.pages.ub.uni-bielefeld.de/cocosy/cooperative-cuisine).
+
+In this directory, you can find additional material for understanding cooperative cuisine and its code.
+
+### Sequence Diagrams
+
+To understand the workflow / messages between components, sequence diagrams provide an easy to follow structure to represent code execution.
+We provide a source file and an image file for each sequence diagram. You can use the source file to edit and plot the diagram at https://sequencediagram.org/.
+
+For the interaction between Study and Game Server and one or more clients (e.g., the pygame gui client) in a study setup, we designed the *"Cooperative Cuisine Study Setup Network Messages"* diagram.
+
+The *"Cooperative Cuisine Environment classes interaction"* shows the interaction between the Environment class and the relevant other classes (Player, Counter, Item, ...) during *each step* and when a new action instruction is called.

docs/sequence-diagrams/seqdia- client-study-game.txt

+title Cooperative Cuisine Study Setup Network Messages
+
+participantgroup #fffacd :0 Clients
+
+materialdesignicons F0379 Client (PyGame2D)
+end
+participantgroup #pink :0 Server
+materialdesignicons F0F48 Study Server
+materialdesignicons F1C9A Game Server
+end
+
+
+activecolor #lightgray
+
+activate Client (PyGame2D)
+
+box right of Client (PyGame2D)#steelblue: <color:#white>Player presses "Start" button</color>
+
+
+Client (PyGame2D)->Study Server: POST://connect_to_tutorial/{participant_id}
+activate Study Server
+
+
+Study Server->Game Server: POST:/manage/create_env/ \n(CreateEnvironmentConfig)
+activate Game Server
+
+space -2
+note left of Game Server: Start env and\nupdate loop
+space -2.5
+Game Server-->Study Server: env_info
+deactivate Game Server
+deactivate Study Server
+
+Client (PyGame2D)->Study Server: POST:/get_game_connection/{participant_id}
+activate Study Server
+
+Study Server-->Client (PyGame2D): Tutorial PlayerInfo
+deactivate Study Server
+
+box right of Client (PyGame2D)#steelblue: <color:#white>Player plays tutorial</color>
+
+Client (PyGame2D)->Study Server: POST:\n/disconnect_from_tutorial/{participant_id}
+activate Study Server
+
+parallel 
+Study Server->Game Server: POST:/manage/stop_env/
+
+activate Game Server
+deactivate Study Server
+space -2.5
+note left of Game Server: Stop env loop
+deactivate Game Server
+
+parallel off
+
+Client (PyGame2D)->Study Server:POST:\n/start_study/{participant_id}/{n_players}
+activate Study Server
+space -4.6
+note right of Study Server: Assign user to study\n(matchmaking)
+
+opt #blue #white no free study
+note right of Study Server: Create Study object
+
+
+Study Server->Game Server: POST:/manage/create_env/ \n(CreateEnvironmentConfig)
+activate Game Server
+Game Server-->Study Server: env_info
+deactivate Game Server
+deactivate Study Server
+
+end
+loop #ff00ff for each level
+
+Client (PyGame2D)->Study Server: POST:\n/get_game_connection/{participant_id}
+activate Study Server
+Study Server-->Client (PyGame2D): Level PlayerInfo
+deactivate Study Server
+
+Client (PyGame2D)->Game Server:CONNECT WEBSOCKET:/ws/player/{client_id}
+activate Game Server
+
+Client (PyGame2D)->Game Server: WS:ready
+activate Game Server
+Game Server->Client (PyGame2D): WS:ok
+deactivate Game Server
+
+loop #ff00ff each frame
+Client (PyGame2D)->Game Server: WS:get_state
+activate Game Server
+Game Server->Client (PyGame2D): WS:state
+deactivate Game Server
+
+Client (PyGame2D)->Game Server: WS:action
+activate Game Server
+Game Server->Client (PyGame2D): WS:ok
+deactivate Game Server
+
+end
+note right of Client (PyGame2D): Notice level ended from state:\nDisconnect WS
+deactivate Game Server
+
+Client (PyGame2D)->Study Server:POST:/level_done/{participant_id}
+activate Study Server
+opt #blue #white all players done
+Study Server->Game Server: POST:/manage/stop_env/
+activate Game Server
+space 0.5
+deactivate Game Server
+opt #blue #white if not last level
+Study Server->Game Server: POST:/manage/create_env/ \n(CreateEnvironmentConfig)
+activate Game Server
+Game Server-->Study Server: env_info
+deactivate Game Server
+deactivate Study Server
+end
+end
+end
+
+box right of Client (PyGame2D)#steelblue: <color:#white>Player presses\"End Study" button</color>
\ No newline at end of file

docs/sequence-diagrams/seqdia-env-classes.txt

+title Cooperative Cuisine Environment classes interaction
+
+
+materialdesignicons F1C77 Environment
+materialdesignicons F0004 Player
+materialdesignicons F05BC Counter
+materialdesignicons F065B Item
+materialdesignicons F0656 Movement
+materialdesignicons F177D Order Manager
+materialdesignicons F15D7 Effect Manager
+
+activecolor #lightgray
+
+==each step (until game ended)==#lightsteelblue
+
+
+group #pink for each [player]
+Environment->Player:progress(delta_time)
+end
+
+Environment->Movement:perform_movement(delta_time, player, counter)
+
+group #pink for each [processing counter]
+Environment->Player:progress(delta_time)
+end
+
+Environment->Order Manager:progress(delta_time)
+
+group #pink for each [effect manager]
+Environment->Effect Manager:progress(delta_time)
+end
+
+
+====
+
+
+==perform action==#lightsteelblue
+
+alt #lightblue type=Movement
+Environment->Player:set_movement(a_data, t+dur)
+note over Player:Set movement data
+opt #blue #white is_interacting
+note over Player:stop interacting
+end
+
+else counter in reach
+
+alt #lightblue type=PickupOrDrop
+
+Environment->Player:put_action(closest_counter)
+
+
+alt #lightblue holding is None
+
+Player->Counter:pick_up(holding)
+box over Counter:holding = occupied_by\n occupied_by = None
+
+Player<--Counter:holding: Item | None
+
+else 
+
+Player->Counter:can_drop_off(holding)
+
+opt #blue #white occupied_by is not None
+
+Counter->Item:occupied_by.can_combine(holding)
+
+end
+
+Player<--Counter:can_drop=bool
+
+alt #lightblue can_drop  =True
+
+Player->Counter:drop_off(holding)
+
+alt #lightblue occupied_by is None
+
+box over Counter: occupied_by = holding\n(return None)
+
+else 
+
+Counter->Item:occupied_by.can_combine(holding)
+
+opt #blue #white can_combine
+
+Counter->Item:occupied_by.combine(holding)
+
+Counter<--Item:Item | None
+
+end
+end
+
+
+Player<--Counter:holding: Item | None
+
+else not PlateDispenser or SinkAddon
+
+Player->Item:holding.can_combine(counter.occupied_by)
+
+opt #blue #white can_combine
+Player->Counter:pick_up(on_hand=False)
+
+alt #lightblue occupied_by is Equipment
+Counter->Item:Release Item
+Counter<--Item:from_counter: Item | None
+
+else
+
+box over Counter:from_counter = occupied_by\n occupied_by = None
+
+end
+
+Player<--Counter:from_counter: Item
+Player->Item:holding.combine(from_counter)
+
+
+end
+
+end
+
+
+else type=Interact
+
+
+Environment->Player:perform_interact_start(closest_counter)
+box over Player:interact=True
+
+
+end
+
+end
+end
\ No newline at end of file