README.md

metadata

title: NPCverse
emoji: ⚔️
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: 6.16.0
python_version: '3.12'
app_file: app.py
pinned: true
license: mit
short_description: Turn anyone into a living RPG character
full_width: true
tags:
  - zerogpu
  - gradio-server
  - image-to-text
  - rpg
  - character-generation

NPCverse

NPCverse turns any uploaded photo into a living RPG character. Upload a portrait, summon a character sheet, then chat with the generated NPC as their lore, powers, quests, secrets, and friendship level evolve.

This HuggingFace Space is built as a fast hackathon demo with a dark RPG web UI, a Gradio Server backend, ZeroGPU allocation, and a PIL-based share-card generator so each summoned character can be exported as a collectible PNG.

How It Works

1. Upload or drag a photo into the NPCverse summoning portal.
2. The backend analyzes the image with a multimodal vision-language model.
3. NPCverse transforms the visual description into structured RPG character JSON.
4. The frontend renders stats, rarity, abilities, lore, quests, secrets, and friendship progress.
5. Chat with the NPC in character, unlock secrets over time, and export a share card.

Model

NPCverse uses openbmb/MiniCPM-V-4.6, a lightweight 1.3B image-text-to-text model from OpenBMB. The model handles both visual analysis and character/chat generation through the HuggingFace Transformers integration.

Badges

• ZeroGPU Explorer
• Spaces Builder
• AI Character Creator
• Sharing is Caring

Local Development

git clone https://huggingface.co/spaces/build-small-hackathon/NPCverse
cd NPCverse
python -m venv .venv
.venv\Scripts\activate      # Windows
# source .venv/bin/activate  # macOS/Linux
pip install -r requirements.txt

# Optional: create a .env file if you hit Hub rate limits locally
# echo HF_TOKEN=hf_... > .env

python app.py

Open http://localhost:7860 after the server starts. The model (openbmb/MiniCPM-V-4.6, ~3 GB) will be downloaded from the Hub on first run.

Environment Variables

Variable	Required	Notes
HF_TOKEN	No	Not required for the public openbmb/MiniCPM-V-4.6 model, but useful locally if you hit Hub rate limits or use private assets.

Hackathon

NPCverse is a submission for Build Small Hackathon 2026, Track 2.