Metadata-Version: 2.4
Name: pgconsole
Version: 0.1.4
Summary: A Python library to add full-featured console to any game.
Author: xdoko01
License: MIT
Project-URL: Homepage, https://github.com/xdoko01/Pygame-Console
Project-URL: Issues, https://github.com/xdoko01/Pygame-Console/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame-ce
Requires-Dist: pgbitmapfont>=0.1.7
Dynamic: license-file

# PyGame-Console
Full-featured game console based on pygame that can be integrated in your python game in order to execute python command/scripts/custom in-game functions.

![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/02_console01_start.png)

## Main Features
* fully configurable look&feel via json - fonts, pictures, commands, console layouts, paddings, scrolling text and more
* history of inputed commands available upon pressing up/down buttons
* scrollable output available upon pressing pgUp/pgDown buttons and/or mouse wheel
* configurable transparency and wallpaper support
* optional header/footer text that can contain dynamic in-game values (time, fps, anything else)
* header/footer layouts supporting scrolling and more
* optional fluent animation during showing/hiding of the console
* commands implemented as a separate python scripts
* support for running custom scripts (batches of console commands) with parameters
* support for colored texts, big inputs, big outputs
* easy integration into your existing code

## Running the Code
All console logic is implemented in the `pgconsole` package. Example game with console implementation is in `examples/demo.py`.
Folders `examples/commands`, `examples/scripts` and `examples/configs` contain configurable console logic tailored for given game. Those can be further modified/extended to implement more logic / commands / scripts into the console.

Make sure you have pygame >= 1.9.4 installed and run the code.

* You will see pygame window with rectancle moving in random directions - simulation of game.

* By pressing `F1` button you can toggle on/off console.

* By pressing `Esc` key or closing the window or typing `exit` will end the program.

## How to Use Console Features

### Python Commands
When instanciating `Console` class you need to specify reference to the main game class that you want to manage. Instance of this class is then referenced as `game`. Using console, you can then use standard python code with this instance. Python commands must start either with `shell` keyword or simple exclamation mark `!`.

Examples of couple python commands that can be used with the example game are below:

* <code>shell print('Hello world') //prints Hello world on console</code>
* <code>!print('Hello world') //same as above</code>
* <code>!game //crints <__main__.TestObject object at 0xXXXXXXXX> i.e. reference to the main object that is govern by the console</code>
* <code>!game.pos = [10,10] //changes position of the game rectancle</code>
* <code>!game.surf.fill((0,0,0)) //changes the color of the game rectancle from white to black</code>
* <code>!game.console.padding.up = 30 //changes the space between upper console corner and first console element (header or other depending on console layout settings)</code>
* <code>!game.cons_get_time() //prints output of the function on the console output</code>
* <code>!1+1 //prints 2 on the output</code>
* <code>![a for a in range(10)] //prints list of values from 0 to 9 on the output</code>      
* <code>!import os //prints 'invalid syntax'. Such python operations are not allowed from the console due to security reasons</code>

![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/07_console01_cmd_py.png)

### Custom Commands
With pygame-console you can specify your own commands. For implementing new command, e.g. <i>dummy</i> that takes one parameter and prints it on the console in the blue color, you need to perform following steps:

* Create a new python file `dummy.py` and place it to `examples/commands` package (or other package specified by the console `global` configuration that can be changed).
* See the existing example python files in the `commands`package for reference. 
  * The python file must contain `initialize` function (you can copy&paste it from example commmands). This function is called automatically when the command is first used. It manages registration of the command with the console.
  * The python file must contain also other function (with any name) that implements the command and is passed `game_ctx` (reference to the game - same as when calling `!game`) and params (command parameters).
* It is good idea to return some value in case of failure. This is important if your custom command is part of some console script (read further).

There are already several custom functions implemented in the example game <code>exit</code>, <code>move</code>, <code>change_res</code>, and <code>test</code>. The <code>move</code> function takes 2 parameters delimited and changes position of the main game rectancle. The <code>exit</code> command exists the game. The <code>list</code> command shows information about registered commands.

![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/03_console01_cmd_input.png)

### Generic Commands
All the non-python shell commands can be listed by typing <code>help</code> or simply <code>?</code> on the command line. The example of generic command can be <code>exit</code> that simply quicks the game. Also by typing <code>help move</code> or simply <code>?move</code> will list description of the command.

![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/08_console01_cmd_gen.png)

### Console Scripts
Python, Custom and Generic commands can be combined together into the file (one command on each line) and can be executed as a script.

Example of invoking such simple script is below:

<code>script example1.scr</code>

![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/09_console01_cmd_script.png)

If there is an error on some line of the script, you are notified on the console with the error message - see below. The error code corresponds to the return value returned in the exception statement in the code of your custom function.

![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/10_console01_cmd_script_err.png)

Console scripts also support parameters. See below the example using parameters for `example3.scr` script. Also, console script can be called from other console script.

<code>script example3.scr x=100 y=200 color=128 name=MyBrick</code>

The body of the script using those parameters is then looking as follows:

```
move $x $y
!print('I have moved the brick named $name')
!game.surf.fill((0, $color,0))
!print('I have colored the brick with $color')
!print("All done!")
```

The parameters are represented as keys starting with `$` in the source of the console script.

![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/12_console01_cmd_script_params.png)

### Dynamic Information in Header/Footer
As mentioned above, header or footer can display dynamic data. Those data are gained as a resulf of calling of some function of the main game class. In the example game, you will see <i>time</i> and game object <i>position</i> as some of the examples of such dynamic values.

If you want to have dynamic values in your console, you need to do the following:

* Implement functions that return the requested values in string time somewhere in your game class or alternativelly in some separate module. In case of our example game there are functions <code>cons_get_pos()</code> and <code>cons_get_time()</code>. Check the code for details.
* Specify the function in configuration json. See the folder `examples/configs` for examples of different configurations. Also, see below parameters `text` and `text_params` where the functions and its placement in the scrolling text is defined.

![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/11_dynamic_text_config.png)

## Changing Console Layout/Configuration
As mentioned in the list of features, console enables heavy configuration. I suggest you to see example console configs in the `examples/configs` directory and get inspiration from 6 configurations that are predifined there - one for truetype font and one for bitmap font.
Below you can see the pictures of those configurations in the game.

### Sample Layout 1
* Scrolling dynamic text in the header and footer
* Transparency of all console parts + wallpaper
* Animation upon displaying hidding of the console set to 2s
* Different fonts for different console parts

with TrueType font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf01.png)

with Bitmap font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf01b.png)

### Sample Layout 2
* Header and footer omitted by configuration
* Transparency of all console parts + wallpaper
* Animation upon displaying hidding of the console - from the bottom - default time 100ms
* Command line input is above console output part
* Different fonts for different console parts

with TrueType font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf02.png)

with Bitmap font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf02b.png)

### Sample Layout 3
* Totaly minimalistic - only header with dynamic text shown
* No transparency, no wallpapers

with TrueType font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf03.png)

with Bitmap font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf03b.png)

### Sample Layout 4
* Minimalistic - only header and footer with dynamic text shown
* No transparency, no wallpapers
* Header and footer are scrolling by different speed

with TrueType font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf04.png)

with Bitmap font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf04b.png)

### Sample Layout 5
* Minimalistic - only input and header with dynamic text shown
* No transparency, no wallpapers

with TrueType font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf05.png)

with Bitmap font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf05b.png)

### Sample Layout 6
* Minimalistic - only input and output with transparency

with TrueType font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf06.png)

with Bitmap font
![screenshot](https://github.com/xdoko01/pygame-console/raw/master/docs/ConsoleConf06b.png)

## How to Integrate PyGame-Console into your Game
 
* Install the Pygame-Console package using `pip` command
```bash
pip -m install pgconsole
```

 * Prepare configuration JSON. Use sample configuration dicts in `examples/configs` directory for inspiration.
 * Import Console class from `pgconsole` package and instantiate it.
 * For switching console on/off call <code>toggle()</code> function.
 * For reading the input keys and process them by console call <code>update()</code> function.
 * For showing the console use <code>show()</code> function. Animation effect is processed internally.
 
 ![screenshot](docs/Integr01.png)
 ![screenshot](docs/Integr02.png)

### Using your own command dispatcher

Unknown commands are by default evaluated as Python (see `do_py_script`). If your game needs to route them
somewhere else - to a server, to its own command registry - supply your own `CommandLineProcessor` subclass
instead of subclassing the whole `Console`:

```python
from pgconsole import Console, CommandLineProcessor

class MyCLI(CommandLineProcessor):
    def default(self, line):
        # Send the unknown command wherever you like instead of running it as Python
        my_game.send_admin_request(line)

console = Console(app=my_game, width=800, config=my_config, cli_factory=MyCLI)
```

The same can be done from the configuration with the `cli_class` key in the `global` section, which takes an
importable path - `"my_game.console.MyCLI"` or `"my_game.console:MyCLI"`. The `cli_factory` argument wins if both
are given. The factory is remembered, so it survives a re-`init()` (for example after `change_res`).

### Writing many lines at once

`Console.write()` re-renders the visible output buffer on every call. When pushing a burst of texts onto the
console - typically from a `logging.Handler` - pass `defer_render=True` and the re-render is done only once per
frame from `update()`/`show()`:

```python
for record in records:
    console.write(record, defer_render=True)
```

### Making the config independent of the working directory

`font_file`, `bck_image` and `script_path` are by default resolved against the current working directory, so a
config with relative paths only works when the game is started from the right place. Pass `base_path` (or set it
in the `global` config section) and the relative values are resolved against it instead:

```python
from pathlib import Path

console = Console(app=my_game, width=800, config=my_config, base_path=Path(__file__).parent)
```

Absolute paths in the config are always left alone, and without `base_path` nothing changes.

> **Security note:** the built-in dispatcher executes arbitrary Python - both via `!`/`do_shell` and via the
> fallback `do_py_script` for unknown commands. That is what makes it a useful debug console, but it means
> **untrusted input (for example anything arriving over the network) must never be passed to `cli.onecmd()`**.


## Changelog

### Release 0.1.1
 * Logging disabled by default
 * Console output buffer is re-rendered after change of the resolution. The text is nicelly align in the new resolution.
 * New console command facilitating change of the resolution - `change_res`.

### Release 0.1.2
 * `pygame-ce` used instead of `pygame` due to problems with python 3.14
 *  Dependency on fixed version of pgbitmapfont library version>=0.1.5

### Release 0.1.3
 * Custom command dispatcher can be injected - `cli_factory` argument of `Console` or `cli_class` key in the `global` config section (#10)
 * Dependency on the obsolete `pathlib` PyPI backport removed - it shadowed the stdlib module and broke installs on modern Python (#12)
 * `write(..., defer_render=True)` renders the output buffer only once per frame instead of once per written line (#13)
 * Configuration without the `global` section no longer crashes `Console.init()` (#18)
 * `Console.clear()` really clears the output - it used to create a stray `log` attribute and clear nothing (#14)
 * `Console.reset()` implemented - re-inits the console with the last used configuration and clears output and input (#15)
 * `SCROLL_LEFT` and `SCROLL_RIGHT` header/footer layouts fixed - they crashed on the first `show()` and now respect the layout speed in ms/px like their `*_CONTINUOUS` counterparts (#16)
 * Centred header/footer text with `font_bck_color` set no longer crashes (#17)
 * Output buffer trimming corrected and moved into one `_trim_buffer()` function - the unprocessed buffer used to be indexed by the length of the wrapped one (#19, #26)
 * `CommandLineProcessor` writing to standard IO instead of the console supports the `color` parameter - colors are emitted as ANSI sequences when the stream is a terminal (#27)
 * Relative `font_file`, `bck_image` and `script_path` config values can be resolved against a `base_path` (constructor argument or `global` config key) instead of the current working directory (#24)
 * `display_lines` is now optional with default 10 - omitting it used to fail later with an opaque `AttributeError` (#23)
 * Trailing whitespace is really removed from the written text - the result of `rstrip()` used to be discarded (#20)
 * A failing `py_script` now shows what the script printed before it failed (#22)
 * Original exception is kept as the cause when a command module cannot be loaded or registered (#21)
 * Tests added for the above - `tests/test_console.py`, runs headless

### Release 0.1.4
 * Dependency on `pgbitmapfont>=0.1.7`, which no longer requires the obsolete `pathlib` PyPI backport. Together with the 0.1.3 change, no install of `pgconsole` pulls it in any more.
 * `requires-python` raised to `>=3.10` to match what `pygame-ce` and `pgbitmapfont` actually support - the declared `>=3.7` was never installable.

## Future Releases
 - [ ] Update on pygame.org
