Merge pull request #569 from Farama-Foundation/core-updates

Add set/get_game_args methods, add support for +win_x/y CVARs on Linux and MacOS

docs/api/cpp/doomGame.md

@@ -316,7 +316,7 @@ See also:
 | :--    | :--                                                           |
 | Python | `add_available_button(buttons: list | tuple[Button]) -> None` |
 
-Set given list of `Button`s (e.g. `TURN_LEFT`, `MOVE_FORWARD`) as available `Buttons`.
+Sets given list of `Button`s (e.g. `TURN_LEFT`, `MOVE_FORWARD`) as available `Buttons`.
 
 Config key: `availableButtons/available_buttons` (list)
 
@@ -333,7 +333,7 @@ See also:
 | :--    | :--                                                                 |
 | Python | `add_available_button(button: Button, maxValue: float = 0) -> None` |
 
-Add [`Button`](./enums.md#button) type (e.g. `TURN_LEFT`, `MOVE_FORWARD`) to available `Buttons` and sets the maximum allowed, absolute value for the specified button.
+Adds [`Button`](./enums.md#button) type (e.g. `TURN_LEFT`, `MOVE_FORWARD`) to available `Buttons` and sets the maximum allowed, absolute value for the specified button.
 If the given button has already been added, it will not be added again, but the maximum value is overridden.
 
 Config key: `availableButtons/available_buttons` (list)
@@ -437,7 +437,7 @@ See also:
 | :--    | :--                                                                            |
 | Python | `set_available_game_variables(variables: list | tuple[GameVariables]) -> None` |
 
-Set list of [`GameVariable`](./enums.md#gamevariable) as available `GameVariables` in the [`GameState`](./gameState.md#gamestate) returned by `getState` method.
+Sets list of [`GameVariable`](./enums.md#gamevariable) as available `GameVariables` in the [`GameState`](./gameState.md#gamestate) returned by `getState` method.
 
 Config key: `availableGameVariables/available_game_variables` (list)
 
@@ -502,21 +502,44 @@ See also:
 Returns the current value of the specified game variable (`HEALTH`, `AMMO1` etc.).
 The specified game variable does not need to be among available game variables (included in the state).
 It could be used for e.g. shaping. Returns 0 in case of not finding given `GameVariable`.
-
+git lo
 See also:
 - [`Enums: GameVariable`](./enums.md#gamevariable)
 
 
-## Game Arguments methods
+## Game arguments methods
+
+
+### `setGameArgs`
+
+| C++    | `void setGameArgs(std::string args)` |
+| :--    | :--                                  |
+| Python | `set_game_args(args: str) -> None`   |
+
+Added in 1.3.0
+
+Sets custom arguments that will be passed to ViZDoom process during initialization.
+It is useful for changing additional game settings.
+Use with caution, as in rare cases it may prevent the library from working properly.
+Using this method is equivalent to first calling [`clearGameArgs`](#cleargameargs) and then [`addGameArgs`](#addgameargs).
+
+Config key: `gameArgs/game_args`
+
+See also:
+- [ZDoom Wiki: Command line parameters](http://zdoom.org/wiki/Command_line_parameters)
+- [ZDoom Wiki: CVARs (Console Variables)](http://zdoom.org/wiki/CVARS)
+
 
+---
 ### `addGameArgs`
 
 | C++    | `void addGameArgs(std::string args)` |
 | :--    | :--                                  |
 | Python | `add_game_args(args: str) -> None`   |
 
-Adds a custom argument that will be passed to ViZDoom process during initialization.
-Useful for changing additional game settings.
+Adds custom arguments that will be passed to ViZDoom process during initialization.
+It is useful for changing additional game settings.
+Use with caution, as in rare cases it may prevent the library from working properly.
 
 Config key: `gameArgs/game_args`
 
@@ -532,7 +555,16 @@ See also:
 | :--    | :--                         |
 | Python | `clear_game_args() -> None` |
 
-Clears all arguments previously added with [`addGameArgs`](#addgameargs) method.
+Clears all arguments previously added with [`setGameArgs`](#setgameargs) or/and [`addGameArgs`](#addgameargs) methods.
+
+
+### `getGameArgs`
+
+| C++    | `std::string getGameArgs()` |
+| :--    | :--                         |
+| Python | `get_game_args() -> str`    |
+
+Returns the additional arguments for ViZDoom process set with [`setGameArgs`](#setgameargs) or/and [`addGameArgs`](#addgameargs) methods.
 
 
 ## Reward methods

docs/api/cpp/utils.md

@@ -13,7 +13,7 @@ The declarations of all the enums can be found in the `include/ViZDoomUtils.h` h
 | :--    | :--                                                           |
 | Python | `doom_tics_to_ms(tics: float, ticrate: int = 35) -> float`    |
 
-Changed in 1.1
+Changed in 1.1.0
 
 Calculates how many tics will be made during given number of milliseconds.
 
@@ -25,7 +25,7 @@ Calculates how many tics will be made during given number of milliseconds.
 | :--    | :--                                                         |
 | Python | `ms_to_doom_tics(ms: float, ticrate: int = 35) -> float`    |
 
-Changed in 1.1
+Changed in 1.1.0
 
 Calculates the number of milliseconds that will pass during specified number of tics.
 
@@ -37,7 +37,7 @@ Calculates the number of milliseconds that will pass during specified number of
 | :--    | :--                                                            |
 | Python | `doom_tics_to_sec(tics: float, ticrate: int = 35) -> float`    |
 
-Added in 1.1
+Added in 1.1.0
 
 Calculates how many tics will be made during given number of seconds.
 
@@ -49,7 +49,7 @@ Calculates how many tics will be made during given number of seconds.
 | :--    | :--                                                           |
 | Python | `sec_to_doom_tics(sec: float, ticrate: int = 35) -> float`    |
 
-Added in 1.1
+Added in 1.1.0
 
 Calculates the number of seconds that will pass during specified number of tics.
 
@@ -70,7 +70,7 @@ you may want to convert them to floating point numbers.
 See also:
 - [`Enums: User variables` in `GameVariables`](./enums.md#user-acs-variables)
 
-Python aliases (added in 1.1): `doom_fixed_to_float(doomFixed: int | float) -> float`
+Python aliases (added in 1.1.0): `doom_fixed_to_float(doomFixed: int | float) -> float`
 
 
 ## Button functions

docs/api/python/doomGame.md

@@ -62,6 +62,7 @@ DoomGame is the main object of the ViZDoom library, representing a single instan
 ## Game Arguments methods
 
 ```{eval-rst}
+.. autofunction:: vizdoom.DoomGame.set_game_args
 .. autofunction:: vizdoom.DoomGame.add_game_args
 .. autofunction:: vizdoom.DoomGame.clear_game_args
 ```

examples/python/README.md

@@ -7,6 +7,9 @@ For the examples to work properly you need to install ViZDoom or create a link t
 ### [audio_buffer.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/audio_buffer.py)
 Demonstrates how to use the audio buffer.
 
+### [automap_buffer.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/automap_buffer.py)
+Demonstrates how to use the automap buffer.
+
 ### [basic.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/basic.py)
 Demonstrates how to use the most basic features of the environment. It configures the engine, and makes the agent perform random actions. It also prints the current state and the reward earned with every action.
 
@@ -25,14 +28,14 @@ Demonstrates how to configure and play the singleplayer game for CIG competition
 ### [delta_buttons.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/delta_buttons.py)
 Shows how delta buttons work (they may take values other than 0 and 1 and can be used for precise movement).
 
-### [format.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/format.py)
-Presents different formats of the screen buffer. [OpenCV](http://opencv.org/) is used to display the images.
-
 ### [fps_test.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/fps_test.py)
 Tests the performance of the environment in frames per second. It should give you some idea how fast ViZDoom works on your hardware.
 
-### [labels.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/labels.py)
-Contains an example of how to implement basic Q-learning on the interface within PyTorch.
+### [gymnasium_wrapper.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/gymnasium_wrapper.py)
+Shows how to use ViZDoom Gymnasium wrapper.
+
+### [labels_buffer.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/labels_buffer.py)
+Demonstrates how to use the labels buffer.
 
 ### [learning_pytorch.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/learning_pytorch.py), [learning_pytorch_test.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/learning_pytorch_test.py)
 Contains an example of how to implement basic Q-learning on the interface within PyTorch.
@@ -58,6 +61,9 @@ Demonstrates how to record an episode and replay it.
 ### [record_multiplayer.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/record_multiplayer.py)
 Demonstrates how to record the multiplayer game and replay it.
 
+### [save_load_game.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/save_load_game.py)
+Demonstrates how to use save and load functionality build into the game engine.
+
 ### [scenarios.py](https://github.com/mwydmuch/ViZDoom/blob/master/examples/python/scenarios.py)
 Presents different scenarios that come with ViZDoom environment.
 

examples/python/audio_buffer.py

@@ -53,7 +53,7 @@
         print(
             "[ERROR] Could not launch ViZDoom. If you see an error above about BiquadFilter and gain,\n"
             "        try setting game.add_game_args('+snd_efx 0'). If that fails, see\n"
-            "        https://github.com/mwydmuch/ViZDoom/pull/486"
+            "        https://github.com/Farama-Foundation/ViZDoom/pull/486"
         )
         exit(1)
 
@@ -63,8 +63,10 @@
     episodes = 3
     audio_slices = []
     for i in range(episodes):
-        print("Episode #" + str(i + 1))
+        print(f"Episode #{i + 1}")
+
         game.new_episode()
+
         while not game.is_episode_finished():
 
             # Gets the state
@@ -87,10 +89,10 @@
         if audio_data.max() == 0:
             print(
                 "[WARNING] Audio buffers were full of silence. This is a common bug on e.g. Ubuntu 20.04\n"
-                "          See https://github.com/mwydmuch/ViZDoom/pull/486\n"
+                "          See https://github.com/Farama-Foundation/ViZDoom/pull/486\n"
                 "          Two possible fixes:\n"
                 "            1) Try setting game.add_game_args('+snd_efx 0'). This my disable some audio effects\n"
-                "            2) Try installing a newer version of OpenAL Soft library, see https://github.com/mwydmuch/ViZDoom/pull/486#issuecomment-889389185"
+                "            2) Try installing a newer version of OpenAL Soft library, see https://github.com/Farama-Foundation/ViZDoom/pull/486#issuecomment-889389185"
             )
         # Save audio file
         wavfile.write("basic_sounds.wav", 22050, np.concatenate(audio_slices, axis=0))

examples/python/automap.py → examples/python/automap_buffer.py

@@ -68,7 +68,7 @@
     sleep_time = 28
 
     for i in range(episodes):
-        print("Episode #" + str(i + 1))
+        print(f"Episode #{i + 1}")
         seen_in_this_episode = set()
 
         # Not needed for the first episode but the loop is nicer.
@@ -87,7 +87,7 @@
 
             game.make_action(choice(actions))
 
-            print("State #" + str(state.number))
+            print(f"State #{state.number}")
             print(
                 "Player position X:",
                 state.game_variables[0],

examples/python/basic.py

@@ -139,7 +139,7 @@
     sleep_time = 1.0 / vzd.DEFAULT_TICRATE  # = 0.028
 
     for i in range(episodes):
-        print("Episode #" + str(i + 1))
+        print(f"Episode #{i + 1}")
 
         # Starts a new episode. It is not needed right after init() but it doesn't cost much. At least the loop is nicer.
         game.new_episode()
@@ -187,7 +187,7 @@
             # r = game.get_last_reward()
 
             # Prints state's game variables and reward.
-            print("State #" + str(n))
+            print(f"State #{n}")
             print("Game variables:", vars)
             print("Reward:", r)
             print("=====================")

examples/python/buffers.py

@@ -89,7 +89,7 @@
     sleep_time = 0.028
 
     for i in range(episodes):
-        print("Episode #" + str(i + 1))
+        print(f"Episode #{i + 1}")
 
         # Not needed for the first episode but the loop is nicer.
         game.new_episode()
@@ -126,7 +126,7 @@
 
             game.make_action(choice(actions))
 
-            print("State #" + str(state.number))
+            print(f"State #{state.number}")
             print("=====================")
 
         print("Episode finished!")

examples/python/cig_multiplayer.py

@@ -60,11 +60,11 @@
     frags = game.get_game_variable(vzd.GameVariable.FRAGCOUNT)
     if frags != last_frags:
         last_frags = frags
-        print("Player " + str(player_number) + " has " + str(frags) + " frags.")
+        print(f"Player {player_number} has {frags} frags.")
 
     # Check if player is dead
     if game.is_player_dead():
-        print("Player " + str(player_number) + " died.")
+        print(f"Player {player_number} died.")
         # Use this to respawn immediately after death, new state will be available.
         game.respawn_player()
 

examples/python/cig_multiplayer_bots.py

@@ -57,7 +57,7 @@
 
 for i in range(episodes):
 
-    print("Episode #" + str(i + 1))
+    print(f"Episode #{i + 1}")
 
     # Add specific number of bots
     # (file examples/bots.cfg must be placed in the same directory as the Doom executable file,
@@ -79,7 +79,7 @@
         frags = game.get_game_variable(vzd.GameVariable.FRAGCOUNT)
         if frags != last_frags:
             last_frags = frags
-            print("Player has " + str(frags) + " frags.")
+            print(f"Player has {frags} frags.")
 
         # Check if player is dead
         if game.is_player_dead():
@@ -94,11 +94,7 @@
     server_state = game.get_server_state()
     for i in range(len(server_state.players_in_game)):
         if server_state.players_in_game[i]:
-            print(
-                server_state.players_names[i]
-                + ": "
-                + str(server_state.players_frags[i])
-            )
+            print(f"{server_state.players_names[i]}: {server_state.players_frags[i]}")
     print("************************")
 
     # Starts a new episode. All players have to call new_episode() in multiplayer mode.

examples/python/cig_singleplayer.py

@@ -52,7 +52,7 @@
             # Use this to respawn immediately after death, new state will be available.
             game.respawn_player()
 
-        print("State #" + str(state.number))
+        print(f"State #{state.number}")
         print("Game variables: ", state.game_variables)
         print("Action:", last_action)
         print("Reward:", reward)

examples/python/cig_singleplayer_host.py

@@ -90,7 +90,7 @@
         last_action = game.get_last_action()
         reward = game.get_last_reward()
 
-        print("State #" + str(state.number))
+        print(f"State #{state.number}")
         print("Game variables: ", state.game_variables)
         print("Action:", last_action)
         print("Reward:", reward)

examples/python/delta_buttons.py

@@ -40,7 +40,7 @@
     sleep_time = 0.028
 
     for i in range(episodes):
-        print("Episode #" + str(i + 1))
+        print(f"Episode #{i + 1}")
 
         game.new_episode()
 
@@ -57,7 +57,7 @@
             if not time % 50:
                 action[3] = -action[3]
 
-            print("State #" + str(state.number))
+            print(f"State #{state.number}")
             print("Action made: ", action)
             print("=====================")
 

examples/python/labels_buffer.py

@@ -101,7 +101,8 @@ def color_labels(labels):
         return tmp
 
     for i in range(episodes):
-        print("Episode #" + str(i + 1))
+        print(f"Episode #{i + 1}")
+
         seen_in_this_episode = set()
 
         # Not needed for the first episode but the loop is nicer.
@@ -147,7 +148,7 @@ def color_labels(labels):
             # Make random action
             game.make_action(choice(actions))
 
-            print("State #" + str(state.number))
+            print(f"State #{state.number}")
             print(
                 "Player position: x:",
                 state.game_variables[0],

examples/python/learning_pytorch.py

@@ -113,7 +113,7 @@ def run(game, agent, actions, num_epochs, frame_repeat, steps_per_epoch=2000):
         game.new_episode()
         train_scores = []
         global_step = 0
-        print("\nEpoch #" + str(epoch + 1))
+        print(f"\nEpoch #{epoch + 1}")
 
         for _ in trange(steps_per_epoch, leave=False):
             state = preprocess(game.get_state().screen_buffer)