Metadata-Version: 2.4
Name: worlds-packer
Version: 1.0.0
Summary: Worlds 游戏平台 .worlds 格式文件生产打包加密一站式工具 | One-stop .worlds packer for Worlds gaming platform
Home-page: https://github.com/xzclin/WorldsPacker
Author: xzclin
Author-email: xzclin <xzclin@users.noreply.github.com>
License: GPL-3.0-only
Project-URL: Homepage, https://github.com/xzclin/WorldsPacker
Project-URL: BugTracker, https://github.com/xzclin/WorldsPacker/issues
Project-URL: Repository, https://github.com/xzclin/WorldsPacker
Keywords: worlds,packer,game,encryption,cli
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: System :: Archiving :: Packaging
Classifier: Topic :: Security :: Cryptography
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Requires-Dist: cryptography>=41.0
Provides-Extra: interactive
Requires-Dist: rich>=13.0; extra == "interactive"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# WorldsPacker

<h1 align="center">🌍 WorldsPacker</h1>
<p align="center">
  <em>Worlds 游戏平台 · .worlds 格式文件生产打包加密一站式工具</em><br>
  <em>One-stop tool for producing, packaging, and encrypting .worlds files for the Worlds gaming platform</em>
</p>

<p align="center">
  <a href="https://github.com/xzclin/WorldsPacker/blob/master/LICENSE">
    <img src="https://img.shields.io/badge/license-GPLv3-blue.svg" alt="GPLv3">
  </a>
  <a href="https://www.python.org/downloads/">
    <img src="https://img.shields.io/badge/python-%3E%3D3.10-blue" alt="Python">
  </a>
</p>

---

**Languages / 语言：**
- [🇨🇳 中文](#-worldspacker--)
- [🇬🇧 English](#-worldspacker---english)

---

# 🇨🇳 WorldsPacker 中文文档

**WorldsPacker** 是一款专为 **Worlds 游戏平台** 设计的 `.worlds` 格式文件生产、打包、加密一站式 CLI 工具。

---

## 🎯 小白友好 — 交互式引导模式

**无需记命令！** 直接运行 `worldspacker` 即可进入图形化的交互菜单：

```bash
worldspacker
```

交互模式会一步一步引导你完成所有操作——选目录、选压缩、设密码，全程菜单化操作。

```
╭──────────────────────── [M] 主菜单 ─────────────────────────╮
│                                                              │
│  1    [P]  打包         将游戏目录打包为 .worlds 文件        │
│  2    [X]  解包         将 .worlds 文件解包到目录           │
│  3    [E]  加密         加密已有的 .worlds 文件              │
│  4    [D]  解密         解密已有的 .worlds 文件              │
│  5    [i]  查看信息     查看 .worlds 文件的详细信息          │
│                                                              │
│  q    退出             退出程序                              │
╰──────────────────────────────────────────────────────────────╯
```

---

## ✨ 功能特性

| 功能 | 说明 |
|------|------|
| 🎮 **交互模式** | 无需记命令，菜单式引导操作 |
| 📦 **打包 (pack)** | 将游戏目录一键打包为 `.worlds` 格式文件 |
| 📂 **解包 (unpack)** | 从 `.worlds` 文件中还原完整目录结构 |
| 🔒 **加密 (encrypt)** | 支持 AES-128-GCM / AES-256-GCM / ChaCha20-Poly1305 |
| 🔓 **解密 (decrypt)** | 使用密码解密已加密的 `.worlds` 文件 |
| 📋 **信息查看 (info)** | 查看 `.worlds` 文件元信息及内部文件列表 |
| 📉 **压缩** | 支持 Zlib / LZMA / BZip2 多种压缩算法 |
| 🔑 **密钥派生** | 采用 PBKDF2-HMAC-SHA256 安全派生密钥 |

---

## ⚡ 下载 & 安装

### 方式一：pip 安装

```bash
pip install worldspacker
```

尚未发布到 PyPI 时，可先本地安装已构建好的包：

```bash
pip install dist/worlds_packer-1.0.0-py3-none-any.whl
```

### 方式二：从 GitHub 克隆

```bash
git clone https://github.com/xzclin/WorldsPacker.git
cd WorldsPacker
pip install -e .
```

### 方式三：直接下载压缩包

下载 [worlds_packer-1.0.0.tar.gz](dist/worlds_packer-1.0.0.tar.gz)：

```bash
tar -xzf worlds_packer-1.0.0.tar.gz
cd worlds_packer-1.0.0
pip install .
```

### 方式四：绿色免安装

```bash
pip install click cryptography rich
python -m worlds_packer --help
```

---

## 🚀 使用指南

### 🎮 交互模式（小白推荐）

```bash
worldspacker
```

### ⌨️ 命令行模式

#### 打包目录为 `.worlds`

```bash
# 基本打包
worldspacker pack ./my_game my_game.worlds

# Zlib 压缩 + AES-256 加密
worldspacker pack ./my_game my_game.worlds -c zlib -e aes-256 -p "密码"

# 仅加密（不压缩）
worldspacker pack ./my_game my_game.worlds -c none -e chacha20 -p "密码"
```

#### 解包

```bash
# 未加密
worldspacker unpack my_game.worlds ./output_dir

# 加密文件需提供密码
worldspacker unpack my_game.worlds ./output_dir -p "密码"
```

#### 查看文件信息

```bash
worldspacker info my_game.worlds
```

#### 加密/解密已有文件

```bash
# 加密已有文件
worldspacker encrypt my_game.worlds -p "密码" -a aes-256

# 解密已有文件
worldspacker decrypt my_game.worlds -p "密码"

# 输出到新文件
worldspacker encrypt my_game.worlds -p "密码" -o encrypted.worlds
```

---

## 📁 .worlds 二进制格式

```
┌──────────────────────────────────────────┐
│  Header (64 bytes)                       │
│  ├─ Magic       "WRLD" (4B)             │
│  ├─ Version     2B                      │
│  ├─ Compression 1B                      │
│  ├─ Encryption  1B                      │
│  ├─ Entry Count uint32 (4B)             │
│  ├─ Total Sizes uint64 x2 (16B)         │
│  ├─ Timestamp   uint64 (8B)             │
│  ├─ Flags       uint32 (4B)             │
│  └─ Reserved    24B                     │
├──────────────────────────────────────────┤
│  Entry Table (128 bytes each)            │
│  ├─ Type / Compression / Encryption      │
│  ├─ Sizes / Offset / Checksum            │
│  ├─ Mode / Name Length                   │
│  ├─ Filename (64 bytes, UTF-8)           │
│  └─ Reserved                             │
├──────────────────────────────────────────┤
│  Data Blocks                             │
│  └─ Each file: [IV] [Ciphertext]         │
├──────────────────────────────────────────┤
│  Encryption Info (50 bytes)              │
│  └─ Algorithm / Salt / IV / Auth Tag     │
└──────────────────────────────────────────┘
```

---

## 🧪 完整示例

```bash
# 1. 准备游戏目录
mkdir -p my_game/assets
echo "Hello World" > my_game/readme.txt

# 2. 打包（压缩 + 加密）
worldspacker pack my_game my_game.worlds -c zlib -e aes-256 -p "pass123"

# 3. 查看信息
worldspacker info my_game.worlds

# 4. 解包到新目录
worldspacker unpack my_game.worlds ./extracted -p "pass123"
```

---

## 📦 依赖

- Python >= 3.10
- click >= 8.0
- cryptography >= 41.0
- rich >= 13.0（仅交互模式需要）

---

## 📄 许可证

本项目基于 **GNU General Public License v3.0 (GPL-3.0)** 开源。

Copyright © 2026 xzclin

---

---

# 🇬🇧 WorldsPacker - English

**WorldsPacker** is a one-stop CLI tool designed for the **Worlds gaming platform** to produce, package, and encrypt `.worlds` format files.

---

## 🎯 Beginner-Friendly Interactive Mode

**No commands to remember!** Just run `worldspacker` to enter the interactive menu:

```bash
worldspacker
```

The guided wizard walks you through every step — select directory, choose compression, set password — all menu-driven.

```
╭──────────────────────── [M] Main Menu ───────────────────────╮
│                                                                │
│  1    [P]  Pack      Package game dir into .worlds            │
│  2    [X]  Unpack    Extract .worlds to directory             │
│  3    [E]  Encrypt   Encrypt existing .worlds                 │
│  4    [D]  Decrypt   Decrypt existing .worlds                 │
│  5    [i]  Info      View .worlds file details                │
│                                                                │
│  q    Quit           Exit the program                         │
╰──────────────────────────────────────────────────────────────╯
```

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🎮 **Interactive Mode** | Menu-driven wizard, no command memorization needed |
| 📦 **Pack** | Package game directory into `.worlds` format |
| 📂 **Unpack** | Extract `.worlds` files back to directory structure |
| 🔒 **Encrypt** | AES-128-GCM / AES-256-GCM / ChaCha20-Poly1305 |
| 🔓 **Decrypt** | Decrypt protected `.worlds` files |
| 📋 **Info** | View metadata and file listing inside `.worlds` |
| 📉 **Compression** | Zlib / LZMA / BZip2 algorithms |
| 🔑 **Key Derivation** | PBKDF2-HMAC-SHA256 for secure key generation |

---

## ⚡ Installation

### Option 1: pip install

```bash
pip install worldspacker
```

Or install from local wheel:

```bash
pip install dist/worlds_packer-1.0.0-py3-none-any.whl
```

### Option 2: Clone from GitHub

```bash
git clone https://github.com/xzclin/WorldsPacker.git
cd WorldsPacker
pip install -e .
```

### Option 3: Download source tarball

Download [worlds_packer-1.0.0.tar.gz](dist/worlds_packer-1.0.0.tar.gz):

```bash
tar -xzf worlds_packer-1.0.0.tar.gz
cd worlds_packer-1.0.0
pip install .
```

### Option 4: Zero-install (run directly)

```bash
pip install click cryptography rich
python -m worlds_packer --help
```

---

## 🚀 Usage

### Interactive Mode (recommended for beginners)

```bash
worldspacker
```

### CLI Mode

#### Pack a directory

```bash
# Basic pack
worldspacker pack ./my_game my_game.worlds

# With compression + encryption
worldspacker pack ./my_game my_game.worlds -c zlib -e aes-256 -p "your-password"

# Encryption only (no compression)
worldspacker pack ./my_game my_game.worlds -c none -e chacha20 -p "your-password"
```

#### Unpack

```bash
# Unencrypted
worldspacker unpack my_game.worlds ./output_dir

# Encrypted
worldspacker unpack my_game.worlds ./output_dir -p "your-password"
```

#### View info

```bash
worldspacker info my_game.worlds
```

#### Encrypt / Decrypt existing files

```bash
worldspacker encrypt my_game.worlds -p "your-password" -a aes-256
worldspacker decrypt my_game.worlds -p "your-password"
worldspacker encrypt my_game.worlds -p "your-password" -o encrypted.worlds
```

---

## 📦 Dependencies

- Python >= 3.10
- click >= 8.0
- cryptography >= 41.0
- rich >= 13.0 (interactive mode only)

---

## 📄 License

This project is licensed under the **GNU General Public License v3.0 (GPL-3.0)**.

Copyright © 2026 xzclin

See the [LICENSE](LICENSE) file for details.
