Skip to content

README.md

Latest commit

 

History

History
164 lines (150 loc) · 5.71 KB

README.md

File metadata and controls

164 lines (150 loc) · 5.71 KB

Welcome to AMIGO - A Multimedia Input to Game Output

Overview

AMIGO is a user-friendly platform designed to enable users to create 2D games without requiring programming expertise. It provides a command-line interface (CLI) to guide users through project setup, asset management, game configuration, and export. AMIGO uses Phaser.js to generate playable games and supports packaging for browser-based play (via Mongoose Web Server) or standalone applications (via Electron.js).

Features

  • No Coding Required: Create games using a guided CLI and YAML configuration.
  • Asset Management: Supports images (.png, .jpg, .jpeg), audio (.mp3), and video (.mp4).
  • Project Validation: Ensures correct folder structure and asset integrity.
  • Game Generation: Converts game.yaml into a playable index.html file with Phaser.js.
  • Export Options:
    • Browser-based games using Mongoose Web Server.
    • Standalone applications using Electron.js.
  • Cross-Device Play: Share games via ZIP files or play locally using a browser or executable.

Installation

Prerequisites

  • Python: Version 3.12.4 or higher.

Setup Instructions

  1. Clone the Repository: 
    git clone https://github.com/Jusuf-Rrustaj/AMIGO.git
  2. Navigate to the Directory: 
    cd AMIGO
  3. Create a Virtual Environment (recommended to avoid package conflicts): 
    python -m venv venv
.\venv\Scripts\activate  # On Windows
source venv/bin/activate  # On macOS/Linux
  4. Install Dependencies: 
    pip install -r requirements.txt
  5. Run AMIGO: 
    python main.py

Usage

Launching AMIGO

  • Run the standalone executable (AMIGO.exe) or execute python main.py for the source version.
  • The platform operates offline and requires no installation.

Main Menu

Upon launch, a CLI mini main menu appears:

? What would you like to do? (Use arrow keys)
 >> Setup a new game project
    Load an existing game project
    About
    Exit
  • Setup a New Game Project: Creates a new project with a folder structure and optional example assets.
  • Load an Existing Game Project: Resumes work on an existing project by specifying its folder path.
  • About: Displays app information and developer credits.
  • Exit: Closes the application.

After selecting or creating a project, a secondary menu offers:

  • Validate Project Structure: Checks for required files and folders (e.g., assets/, images/, audio/).
  • Build Game: Guides users to create a game.yaml file defining game structure, scenes, and logic.
  • Generate Game: Converts game.yaml into a playable index.html file with Phaser.js.
  • Package Game for Export: Packages the game for browser (Mongoose) or standalone (Electron.js) distribution.
  • Play Game: Launches the game locally using start_game.bat (Mongoose) or opens it in a browser.

Project Structure

When creating a new project, AMIGO generates a folder structure:

  • Minimal Structure (without example assets): 
    my-AMIGO-game/
└── assets/
    ├── library/
    │   └── phaser.js
    └── ui/
        └── icon.ico
  • With Example Assets: 
    my-AMIGO-game/
├── assets/
│   ├── audio/
│   │   ├── correctSound.mp3
│   │   └── wrongSound.mp3
│   ├── images/
│   │   ├── background_level.jpg
│   │   ├── background.png
│   │   ├── bird.jpg
│   │   ├── cat.jpeg
│   │   ├── game_logo.png
│   │   └── tree.jpg
│   └── ui/
│       └── icon.ico
├── library/
│   └── phaser.js
├── game.yaml
└── index.html

Asset Management

  • Place assets in assets/images/ (.png, .jpg, .jpeg), assets/audio/ (.mp3), or assets/video/ (.mp4).
  • Reference assets in game.yaml using relative paths, e.g.: 
    assets:
  images:
    - key: sun
      path: assets/images/sun.jpg
  audio:
    - key: correctSound
      path: assets/audio/correctSound.mp3

Editing game.yaml

  • The game.yaml file defines game settings, scenes, assets, objects, variables, and logic.
  • Edit it manually with a text editor (e.g., Visual Studio Code) for precise control.
  • Example configuration: 
    game:
  type: AUTO
  width: 1024
  height: 768
  backgroundColor: '#f0f0f0'
  scenes:
    - MainMenu
    - Level1
scenes:
  - name: MainMenu
    assets:
      images:
        - key: logo
          path: assets/images/game_logo.png
    gameObjects:
      - type: text
        id: title
        x: 525.0
        y: 390.2
        content: Adventure in Picture World!
        style:
          fontSize: 40
          fontFamily: Arial
          color: '#ffffff'

Exporting the Game

  • Mongoose Web Server:
    • Generates start_game.bat, mongoose.exe, and copies index.html and assets.
    • Run start_game.bat to launch the game in a browser at http://localhost:8000.
  • Electron.js:
    • Requires Node.js (install prompted if missing).
    • Creates export_electron/ with game.exe and supporting files.
    • Launch by double-clicking game.exe or a shortcut in the project root.

Sharing the Game

  • After exporting, choose to create a ZIP file:
    • Mongoose: Creates game_title_hostable.zip with start_game.bat, index.html, and assets.
    • Electron: Creates game_title_standalone.zip with game.exe and dependencies.
  • Recipient Instructions:
    • Mongoose: Unzip, run start_game.bat to play in a browser.
    • Electron: Unzip, double-click game.exe or the shortcut to play.