Metadata-Version: 2.4
Name: NexusFine
Version: 1.0.3
Summary: AI驱动的物理游戏引擎 - 聚合设计
Author: bengtiaotiao
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.0
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NexusFine

Physics engine for 2D/3D game prototyping with optional AI acceleration.

## Installation

```bash
pip install NexusFine
```

## Quick Start

```python
from nexusfine import NF

api = "sk-xxxxxx"
x = "x_axis"
y = "y_axis"

NF(api)
NF(x)
NF(y)
NF(x, y)
NF("Game.exe")
```

## Modules

| Module | Description | Provides |
|--------|-------------|----------|
| NF | Bullet physics | Bullet(), Steam() |
| NB | Ball physics | Ball() |
| NC | Cloud physics | Cloud() |
| NS | Configuration | config(), apply() |

## Physics Objects

### Bullet

```python
from nexusfine import NF

bullet = NF.Bullet(
    x=0, y=10,
    vx=5, vy=0,
    gravity=300
)
bullet.update(0.016)
```

### Ball

```python
from nexusfine import NB

ball = NB.Ball(
    x=0, y=5,
    radius=10,
    gravity=300,
    bounce=0.8,
    ground_y=600
)
ball.update(0.016, width=800, height=600)
```

### Cloud

```python
from nexusfine import NC

cloud = NC.Cloud(
    x=0, y=5,
    vx=0.5, vy=0.1
)
cloud.update(0.016)
```

### Steam

```python
from nexusfine import NF

steam = NF.Steam(
    x=0, y=0, z=0,
    rise_speed=0.5,
    diffusion=0.3
)
steam.update(0.016)
```

## AI Configuration

### Enable AI with DeepSeek

```python
from nexusfine import NB, NS

api = "sk-your-deepseek-key"
NS.apply(NB, mode="A", duration=60)
NB(api)
NB("x")
NB("y")
NB("x", "y")

NB.set_ai("deepseek")

ball = NB.Ball(x=400, y=300, radius=20)
ball.engine = NB
ball.update(0.016, 800, 600)
```

### Enable AI with OpenAI

```python
NB.set_ai("openai", model="gpt-3.5-turbo")
```

### Enable AI with Local Ollama (Free)

```python
NB.set_ai("ollama", model="llama3.2", api_base="http://localhost:11434/api/generate")
```

### Mode Reference

| Mode | Description | AI Status |
|------|-------------|-----------|
| A | AI Enhanced | Enabled |
| B | Balanced | Enabled |
| C | Local Only | Disabled |

```python
from nexusfine import NF, NS

NS.apply(NF, mode="C", duration=60)
```

## Parameters Reference

### Bullet Parameters

```
Bullet(x, y, vx, vy, gravity)
```

| Parameter | Description | Default |
|-----------|-------------|---------|
| x | Initial X position | 0 |
| y | Initial Y position | 0 |
| vx | Initial X velocity | 5 |
| vy | Initial Y velocity | 0 |
| gravity | Gravity (pixels/sec²) | 300 |

### Ball Parameters

```
Ball(x, y, radius, gravity, bounce, ground_y)
```

| Parameter | Description | Default |
|-----------|-------------|---------|
| x | Initial X position | 0 |
| y | Initial Y position | 0 |
| radius | Ball radius | 10 |
| gravity | Gravity (pixels/sec²) | 300 |
| bounce | Bounce coefficient (0-1) | 0.8 |
| ground_y | Ground position | 600 |

**Ball.update(dt, width, height)**
- `dt`: Time step
- `width`: Screen width (enables wall collision)
- `height`: Screen height (enables wall collision)

### Cloud Parameters

```
Cloud(x, y, vx, vy)
```

| Parameter | Description | Default |
|-----------|-------------|---------|
| x | Initial X position | 0 |
| y | Initial Y position | 0 |
| vx | X velocity | 0.5 |
| vy | Y velocity | 0.1 |

### Steam Parameters

```
Steam(x, y, z, rise_speed, diffusion)
```

| Parameter | Description | Default |
|-----------|-------------|---------|
| x | Initial X position | 0 |
| y | Initial Y position | 0 |
| z | Initial Z position | 0 |
| rise_speed | Upward speed | 0.5 |
| diffusion | Spread amount | 0.3 |

## AI Providers

| Provider | Type | Key Format | Setup |
|----------|------|------------|-------|
| DeepSeek | Cloud | sk-xxxxxx | Get from platform.deepseek.com |
| OpenAI | Cloud | sk-xxxxxx | Get from platform.openai.com |
| Ollama | Local | Not required | Install ollama.ai |

## Fallback Behavior

When AI is enabled but fails (network error, invalid key, timeout):
- The engine **automatically falls back to local physics**
- Your game continues running without interruption
- No manual error handling required

## Requirements

```
Python >= 3.6
requests >= 2.25.0
```

## License

MIT
