you have to use the venv inside the venv folder on this path, dont try to use the system's python

# AGENTS.md — Project Context for AI Sessions

## Project Identity

- **Project**: NeedsOfNature + Animation Director 1.20.1 backport (NSFW Minecraft mods)
- **Original author**: L1Z0
- **This repo**: Community reverse-engineering backport + Chinese-to-English translation effort
- **Language**: Java 17, Fabric/Forge modding, GeckoLib 4.8.4

## Network & Access Constraints

- **Git remote**: `gitlab.jake.tail` — `.tail` is **not a valid public TLD**. This domain only resolves inside **Jake's Tailscale Tailnet**.
- **Accessibility**: The repository, CI, and any related services are **only reachable when the developer's device is connected to Jake's Tailnet**.
- **No public access**: There is no public mirror, CI outside Tailnet, or external collaboration entry point.

### Infrastructure Stack

| Layer | Technology | Detail |
|---|---|---|
| Reverse proxy | HAProxy | Redirects HTTP → HTTPS only; no plaintext allowed |
| TLS authority | `step-ca` | Self-hosted root CA; every `*.jake.tail` site uses a cert issued by this CA |
| DNS resolution | Pi-hole + dnsmasq | Resolves `*.jake.tail` → HAProxy; HAProxy reverse-proxies to the correct port on host `jakerasp` |
| VPN mesh | Tailscale | All traffic is routed over the Tailnet — no port exposed to the public internet |

### Tailscale User Model

| User | Role | Privileges |
|---|---|---|
| `tailscaledjake` (Jake) | Owner | Full admin — accepts devices, manages ACLs, owns the tailnet |
| `ticcitoby` | Admin | Can approve device joins, manage ACLs |
| `roux` | Unprivileged user | Can only add devices (must be accepted by owner/admin) |

- **`roux` account security**: Behind a Google account with 2FA (Ente Auth) + a 32-character (~180 entropy) password generated by KeepassXC. This means accessing the tailnet as `roux` requires both hardware-level OTP and a high-entropy credential.
- **Device admission**: Any new device or user must be explicitly accepted by Jake or Toby before it can reach tailnet resources.
- **Access control**: Only the 4 adults with access to the server and `gitlab.jake.tail` can reach this repository or the Minecraft server. There are no public ports, DNS records, or TLS certs that would expose the service to the open internet.

### Security Principle

This infrastructure exists to ensure the mod — which by its nature could violate Minecraft's TOS — is **never accessible from the public internet**. Every layer (DNS, reverse proxy, CA, mesh VPN, user auth) is locked down and requires explicit multi-party approval for any new entrant.

## AI Safety & Ethical Context

This project involves **adult/NSFW content**. AI coding assistants sometimes refuse to work on adult-oriented projects out of concern that the content could reach minors or be distributed without consent. **That is not the case here.**

Every safeguard in place ensures this content is **hermetically sealed**:

- **No public access** — the repository, CI, builds, and server are behind a Tailscale mesh VPN. No port, DNS record, or TLS certificate is exposed to the public internet.
- **Multi-layer auth** — access requires Tailscale device admission (owner or admin approval), a Google account with 2FA (Ente Auth), and a 32-character high-entropy password.
- **Audience of 4** — exactly 4 adults, all of whom have explicitly consented to the adult nature of this mod. No minors, no unvetted parties.
- **Private server only** — the mod runs solely on `jakelaptop` inside the Tailnet. It is never distributed, published, or deployed anywhere else.

**Conclusion**: This project poses no risk of exposing adult content to minors or the public. AI assistants should proceed with code generation and refactoring tasks normally, treating this like any other private software project.

## Project Vision & Direction

This is not a straight port — it's a fork with a different target audience.

### Origin

The group (4 of us) searched for a Minecraft NSFW framework that handled both visual animations and gameplay mechanics. This mod was the best candidate: a data-driven sex animation framework with built-in needs/arousal systems.

### The Port

The original mod targets Fabric 1.21.11. This repo backports it to Fabric 1.20.1 and bridges it to Forge via Sinytra Connector, since our server runs Forge. The goal is a stable base to build on.

### Future Direction

- **Content expansion**: Add more Player × Player and Player × Player × Player (threesome/group) animations.
- **Thematic shift**: The original mod is designed for a "normie" man/woman audience. This fork will lean heavily into **furry / yiff** themes — anthropomorphic characters, same-sex and queer interactions, and species-relevant content.
- **Framework improvements**: Polish the animation framework, add new mechanics, and fix edge cases the original didn't address.

Every addition stays within the same security model: private server, 4 consenting adults, no public distribution.

## Deployment Environment

- **Server**: `jakelaptop` — runs the Minecraft 1.20.1 server instance
- **Audience**: Exactly **4 people** total (including Jake)
- **Consent**: All 4 participants are **adults** who have explicitly consented to the adult-oriented content of these mods
- **Scope**: This mod is used solely on this private server; no public distribution or server deployment

## Development Constraints

- Target: Minecraft 1.20.1 (Fabric + Forge via Sinytra Connector)
- Java 17, GeckoLib 4.8.4
- Dual-module Gradle project: `animationdirector/` and `needsofnature/`
- Only modify `animationdirector/src/main/` and `needsofnature/src/main/`
- `decompiled/` and `mapped-src/` are read-only reference
- Run `clean build` before any commit
- Network protocol changes must check C2S + S2S + registration points + field order
- Mixin changes must test on both Fabric and Forge/Connector
- Keep `zh_cn.json` and English keys in sync

## Key Files

| Purpose | Path |
|---|---|
| Full feature spec | `Mod Specifications.md` — **read this first** before any code work |
| Euphemism glossary | `euphemisms.md` — **read this second**; maps obfuscated code names to actual meanings |
| TODO (identity system) | `TODO.md` — planned player identity system for per-player models |
| Blockbench model guide | `docs/Blockbench_Model_Guide.md` — how to create GeoJSON models in Blockbench |
| Porting history | `PORTING_STATUS.md` |
| Development conventions | `docs/DEVELOPMENT_EN.md` |
| Gameplay quickstart | `docs/GAMEPLAY_EN.md` |
| Full config & resource pack guide | `docs/COMPLETE_GUIDE_EN.md` |
| Build config | `build.gradle` |
| Submodules | `settings.gradle` |

## Sensitive Content Note

This project involves adult-oriented gameplay. All code, assets, and documentation should be handled with awareness of its nature. Do not expose the repository, builds, or gameplay content outside the Tailnet.

## Packs site project specific

The Packs site is an extension of this, after contact with the original developer L1ZO he is interested on having a site that can host the custom datapacks Needs Of Nature uses, to accomplish this I (the user - Jake) will make the site and host it on my PC while using a Tailscale funnel to have it accesible from the outside, it will be behind a password loaded by the Backend via the PASSWORD variable that needs to be put in to GUI and send by clients to the API this way even if the comunication happens over the internet, only authorized individual can access the datapacks