Shinobi Saga — Naruto vs Sasuke 2D Pygame Fighter Arcade

A compact 2D fighting game built with Python and Pygame. Two shinobi face off in short, arcade-style bouts. The project focuses on sprite animation, hit detection, weapon attacks, health and UI screens. It serves as a playable demo and a code sample for game development in Python.

Badges

Table of Contents

• About
• Features
• Screenshots
• Controls
• Gameplay mechanics
• Install & Run
• Development setup
• Project structure
• Assets & art
• Contributing
• License
• Credits
• Topics

About

Shinobi Saga recreates a short duel between two iconic shinobi. The code uses Pygame for rendering, input, sound, and timing. Characters have frame-by-frame animations, a combo system, weapon attacks, and a simple state machine for actions. UI screens include title, pause, round results, and a game over screen.

Features

• 2D side-view fighting arena
• Animated sprites for two playable characters
• Health bars and round system
• Melee and ranged weapon attacks
• Hit detection with knockback
• Simple combo chaining and stun frames
• Title, pause, and result screens
• Sound effects and music
• Gamepad support (optional)
• Clean, commented Python code for learning

Screenshots

Pygame logo (engine)

Ninja silhouette (placeholder art)

Sample HUD mockup (health bars and timer)

Controls

Default keyboard layout (customize in settings file):

• Move left: Left Arrow
• Move right: Right Arrow
• Jump: Up Arrow
• Crouch: Down Arrow
• Light attack: Z
• Heavy attack: X
• Special / Throw: C
• Block: V
• Pause: Esc

Gamepad mapping (XBOX-style)

• Left stick: Move
• A: Jump
• X: Light attack
• Y: Heavy attack
• B: Special
• LB: Block
• Start: Pause

Gameplay mechanics

• Health bars: Each player has a health bar. Damage reduces health. A round ends when one health bar hits zero.
• Combo system: A chain of light and heavy attacks increases combo counter and damage.
• Stun frames: Repeated hits can cause a short stun. The player cannot act during stun.
• Weapon attacks: Characters can throw a short-range projectile. Projectiles have collision and lifespan.
• Knockback: Strong hits push the target back. The engine applies a short physics impulse.
• Rounds: Best of three rounds by default.
• UI: Score, round timer, and player names display on HUD.

Install & Run

Requirements

• Python 3.8 or newer
• pip

Install dependencies

• Create a virtual environment:
  • python -m venv venv
  • venv\Scripts\activate (Windows) or source venv/bin/activate (macOS/Linux)
• Install packages:
  • pip install -r requirements.txt
  • If no requirements file, install Pygame:
    • pip install pygame

Release download and execution

• Download the release package from the Releases page: https://github.com/antonella1973/Shinobi-Saga/releases
• The release contains the build you need to run. Download the packaged file and execute it.
  • Windows: run Shinobi-Saga.exe or unzip and run the provided .exe
  • macOS: open the app bundle or run the included script
  • Linux: run the launcher script or run python main.py inside the unpacked folder
• If you prefer the source, clone this repo and run main.py after installing dependencies.

Development setup

Clone the repo

• git clone https://github.com/antonella1973/Shinobi-Saga.git
• cd Shinobi-Saga

Run from source

• Activate venv
• pip install -r requirements.txt
• python main.py

Common dev tasks

• Run lint: flake8 src/
• Run formatter: black src/
• Run tests: pytest tests/ (if tests exist)

Project structure

A typical layout:

• src/ or shinobi_saga/
  • main.py — game entry point
  • game.py — main game loop and scene manager
  • player.py — player class, states, inputs
  • enemy.py — AI logic (if any)
  • sprites/ — sprite sheets and animation data
  • assets/
    • sounds/
    • music/
    • fonts/
  • ui/ — HUD and menu screens
  • physics.py — collision helper and simple physics
• assets/ — packaged art and audio for releases
• docs/ — design notes and sprite specs
• LICENSE
• README.md

Assets & art

Sprites use sprite sheets with fixed frame sizes. Animations use frame indices and frame durations. The repo stores small placeholder art. For a full release build, the assets folder contains all final PNGs and audio clips.

If you add art:

• Keep sprite sheets in src/sprites/
• Place sound files in src/assets/sounds/
• Use OGG for music and WAV for short SFX
• Keep file names descriptive: player_naruto_run.png, sasuke_attack_1.wav

Performance tips

• Use surface.convert_alpha() on loaded images
• Cache scaled sprites to avoid repeated transforms
• Limit FPS to a stable value (e.g., 60) via clock.tick(60)
• Batch blits where practical

Contributing

• Fork the repo
• Create a feature branch: git checkout -b feat/new-move
• Make changes in small commits
• Add tests for new logic
• Submit a pull request with a clear description of changes and gameplay impact

When you open a pull request, mention:

• What you changed
• Why you changed it
• How to test the change

Style guidelines

• Keep functions under ~120 lines
• Document public methods with a one-line docstring and short example
• Use typing hints for key functions
• Keep global state minimal

Testing

• Unit-test game logic that does not touch Pygame display
• Use monkeypatch or dependency inversion to test input handlers
• For integration tests, run headless or use a minimal frame buffer

Troubleshooting

• If Pygame fails to initialize audio, set SDL_AUDIODRIVER to "dsp" or "alsa" on Linux.
• If the game window fails to open, ensure your Python and Pygame versions match system bitness.
• If a required file is missing after download, re-download the release package from https://github.com/antonella1973/Shinobi-Saga/releases and unpack it again.

License

This project uses the MIT License. See LICENSE for full terms.

Credits

• Engine: Pygame
• Art samples: placeholder SVG and public domain icons
• Sound: credited packs (check assets/credits.txt)
• Design and code: repository author and contributors

Topics

anime-game, game-development, naruto, naruto-game, naruto-vs-sasuke, open-source, pygame, pygame-games, python, sasuke, sasuke-game, shinobi-saga

Contact & Links

• Releases and downloadable builds: https://github.com/antonella1973/Shinobi-Saga/releases
• Issues: open an issue on GitHub
• Pull requests: welcome for features, bug fixes, and assets

Appendix — Useful commands

• Create venv: python -m venv venv
• Activate (Windows): venv\Scripts\activate
• Activate (macOS/Linux): source venv/bin/activate
• Install: pip install -r requirements.txt
• Run: python main.py
• Style: black src/ && flake8 src/

Assets used in README

• Pygame logo: https://www.pygame.org/docs/_static/pygame_logo.png
• Ninja icon (public SVG): https://upload.wikimedia.org/wikipedia/commons/1/16/Ninja_icon.svg
• Timer icon: https://upload.wikimedia.org/wikipedia/commons/8/8f/Timer_icon.svg

Releases

Download the packaged build from the Releases page and execute the included file. Visit: https://github.com/antonella1973/Shinobi-Saga/releases for the downloadable builds and assets.