Metadata-Version: 2.4
Name: TofuByte
Version: 0.4.0
Summary: Terminal game with sweet block of tofu character!
Author-email: Cvaniak <igna.cwaniak@gmail.com>
License: GPL-3.0-or-later
Project-URL: Homepage, http://github.com/Cvaniak/TofuByte
Requires-Python: <4,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: textual==5.0.1
Requires-Dist: tomli>=2.3.0; python_version < "3.11"
Requires-Dist: pynput>=1.7.6
Requires-Dist: httpx>=0.28.1

<p>
    <img src="./animation.svg" hspace="10" >
    <img src="./logo.svg" hspace="10" >
</p>

Terminal game with sweet block of [tofu](https://fonts.google.com/knowledge/glossary/tofu) character!

![quick-demo](https://github.com/user-attachments/assets/9a9481f1-b048-4f3d-b395-df138211279b)

> [!WARNING]  
> Game uses Pynput to handle input. If you got banner with input system problems, read the Troubleshooting section.

## How to install

### Prerequisites

To properly display all characters:

- Use a modern terminal emulator.
- Install a Unicode-ready font (e.g., NerdFonts).
- Ensure your shell environment is configured to use UTF-8 encoding.

### Installation and running TofuByte

With [`uv`](https://docs.astral.sh/uv/getting-started/installation/)

```bash
uvx tofubyte
```

or using [`pipx`](https://pipx.pypa.io/stable/installation/)

```bash
pipx install tofubyte
tofubyte
```

If you prefer mauall Installation:

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install the package
pip install tofubyte

# Run the game
tofubyte
```

## Input system

The game uses [`pynput`](https://pynput.readthedocs.io/en/latest/) for handling keyboard input. As it is not a terminal-native input system, it might not work as expected in all terminal environments or operating systems.

I plan to implement scroll mode in the game that will not require any additional input system.

## Troubleshooting

### Input issues (Pynput)

If keyboard input is not working, the game should inform you with an in-game message. This is likely due to `pynput` compatibility issues with your terminal or operating system. It might also be affected by whether you are running X11 or Wayland.

Currently, you can try the following:

- Run the game with `sudo tofubyte`
- Run the terminal emulator with `sudo`
- Run the game with `PYNPUT_BACKEND_KEYBOARD=uinput tofubyte` (This forces `pynput` to use the `uinput` backend, which might be more compatible on some Linux systems.)
- Try running the game in a different terminal emulator:
  - Guake (should work without `sudo`)
  - Wezterm (should work without `sudo`)
  - Kitty (requires `sudo`)
  - Ghostty (requires `sudo`)
  - Terminator (requires `sudo`)
- On macOS, you can try running with `sudo` or refer to [this StackOverflow comment](https://stackoverflow.com/a/54659886) for alternative solutions.
- Windows WSL - As the

Further reading and potential solutions can be found in the [Pynput Documentation](https://pynput.readthedocs.io/en/latest/limitations.html#mac-osx).

If you are concerned about how `Pynput` is used, feel free to review the available source code.

Also if you found solution for your problem, share this in the issue so it can help others.

## Map Editing

<img width="2326" height="1366" alt="Screenshot_20260210_232553" src="https://github.com/user-attachments/assets/34ce8155-f2dc-4d09-8b51-04e890ad78b6" />

You can edit and create maps with built in editor!

> [!WARNING]  
> Currently when creating new map it is created inside user directory, hard to access. You can "Download" map from editor, to get in directory from which you run the app.

There are some keybindings worth to know:

- ctrl+mouse_move - resize selected
- ctrl+mouse_click - selects multiple
- ctrl+v - to copy-paste selected objects

Some tutorial will be provided soon.

<img width="2290" height="1348" alt="Screenshot_20260210_232854" src="https://github.com/user-attachments/assets/533fb464-74d4-47f9-bccf-cb88b3ccb4c6" />

## Community Maps

TofuByte supports community-created maps! You can browse them on GitHub by searching for the `tofubyte-map` topic.

> [!WARNING]
> The author does not maintain these community maps and takes no responsibility for their content or any consequences arising from their download and use. Please make this game a safe and fun place to be.

Explore community maps on GitHub: [https://github.com/topics/tofubyte-map](https://github.com/topics/tofubyte-map)

To play a community map:

1. Download the `.json` map file from GitHub.
2. Place the downloaded `.json` file into your custom maps directory.
   This directory is typically located at `~/.local/share/TofuByte/maps/custom_maps` on Linux, but the exact path might vary depending on your operating system.

## Contributing Your Own Maps to GitHub

If you've created a map you'd like to share with the TofuByte community and make it discoverable through the in-game browser, follow these steps:

1.  **Create a New GitHub Repository:** Create a new public repository on GitHub for your map.
2.  **Upload Your Map File:** Add your `.json` map file (created using the in-game editor) to this new repository. It's recommended to include a `README.md` in your repository with a description of your map, screenshots, and any special instructions.
3.  **Add the `tofubyte-map` Topic:** To make your repository discoverable by the TofuByte community maps browser, you _must_ add the `tofubyte-map` topic to your repository.
    - On your GitHub repository page, look for the "About" section on the right sidebar.
    - Click on the gear icon (⚙️) or "Manage topics" to edit topics.
    - Add `tofubyte-map` to the list of topics and save your changes.

Your map will now be browsable in the TofuByte client!

## Development

There are some additional tools I have used during developed. They show some stats and other things that helped debug:

```bash
uv run textual run --dev tofu_byte.command_line:run --debug contact_dir,step,fps,footer,player_stats
```

## Speciall thanks

As always, huge shot out to [Textualize](https://github.com/Textualize) team!  
**TofuByte** was created as result of exploration of what can be done to display game with such a nice framework as [Textual](https://github.com/textualize/textual/).

## License and Community

This is my little independent game, developed in my personal time.

As I have many plans for further changes and wish to maintain a clear mental model of the project, I am not currently planning to accept code contributions.

However, feedback is very welcome.
If you encounter bugs, issues, or have feature ideas, please open an issue on GitHub.

I also plan to implement features for uploading, browsing, and downloading maps directly from within the game.
