BETA - AIPlayers v1.0

PLEASE NOTE THIS IS IN BETA AND STILL BEING WORKED ON!

AIPlayers — Realistic AI Chat + Fake Players

Overview

• AI-driven, natural replies to player chat using an external AI provider.
• Random fake player joins/leaves and occasional small talk to make your server feel alive.
• Optional tab list appearances for fake players when ProtocolLib is installed.
• Lightweight, async HTTP client (no external JSON libs) with a safe fallback text generator.
• Fully configurable with debug logging to help troubleshoot.

Requirements

• Server: Paper 1.21.x (or compatible) on Java 21
• Network: Outbound HTTPS to your AI provider (default OpenAI)
• Optional: ProtocolLib (for fake players to appear in the tab list)

Installation
1) Place the plugin jar in your server’s plugins folder.
2) Start the server once to generate the default config.
3) Open plugins/AIPlayers/config.yml and set your AI provider API key and model.
4) (Optional) Install ProtocolLib to show fake players in the tab list.
5) Use /aiplayers reload to apply changes, or restart the server.

Quick start (config.yml)

• Set your AI provider settings under ai.
• Tune how often and how fast replies happen under chat.
• Configure fake player names and timing under fakePlayers and fakeChat.
• Enable debug for visible logs.

Example config excerpt
Note: Replace the API key with your own (keep it secret).

ai:
enabled: true
baseUrl: "https://api.openai.com/v1"
apiKey: "YOUR_API_KEY_HERE"
model: "gpt-4o-mini"
temperature: 0.8
maxTokens: 80
systemPrompt: >-
You are a casual Minecraft player chatting on a friendly survival server.
Reply briefly (one sentence), informal and friendly, never roleplay as admin, avoid commands.
Keep it natural and context-aware.

chat:
responseChance: 0.35
minDelayTicks: 20
maxDelayTicks: 80
minLength: 5
maxLength: 22

fakePlayers:
enabled: true
names: [Luna, Max, Kai, Nova, Ivy, Jax, Finn, Zara]
minJoinIntervalSeconds: 30
maxJoinIntervalSeconds: 180
minSessionSeconds: 45
maxSessionSeconds: 300
joinMessageFormat: "%s joined the game"
leaveMessageFormat: "%s left the game"

fakeChat:
enabled: true
minIntervalSeconds: 25
maxIntervalSeconds: 120
minLength: 4
maxLength: 16

debug:
enabled: false
logAiRequests: false
logAiResponses: false

What it does

• AI Replies to Players:
• Listens to chat and, based on chat.responseChance, responds like a normal player.
• Uses your configured AI provider (or a built-in fallback if the provider is disabled/unavailable).
• Adds realistic typing delays before sending the message.

• Fake Player Activity:
• Randomly broadcasts join/leave messages for configured names.
• Keeps them online for a random session length.
• Occasionally sends small talk messages using AI (or fallback), so the server feels active.

• Tab List (optional):
• If ProtocolLib is installed, fake players are added to and removed from the tab list automatically.
• If ProtocolLib isn’t on your server, the rest of the plugin still works; only tab entries are skipped.

Commands & Permissions

• /aiplayers reload
• Description: Reloads the plugin configuration from disk.
• Permission: aiplayers.reload (default: op)

Tuning Tips

• Want more/less AI replies?
• Increase/decrease chat.responseChance.
• Want replies to be snappier or slower?
• Decrease/increase chat.minDelayTicks and chat.maxDelayTicks.
• Too verbose or too terse?
• Adjust ai.maxTokens and ai.temperature for the provider.
• Fallback length limits: chat.minLength/chat.maxLength and fakeChat min/max length.
• Fake player realism:
• Use a balanced pool of names and vary min/max join/session seconds.

Debugging

• Set debug.enabled to true to log key decisions and events:
• Whether a message triggered a reply and the random roll used.
• Who will reply, and after how many ticks.
• AI requests/responses (when logAiRequests/logAiResponses are true).
• Fake player join/leave schedules and actions.
• Fake chat scheduling and broadcast events.

Safety & Costs

• Keep your API key private. Do not commit it to public repos or share it in screenshots.
• Using an AI provider may incur usage fees; set reasonable limits (maxTokens, responseChance) and monitor your usage.

Compatibility Notes

• Works best with Paper 1.21.x. Other forks may work but aren’t guaranteed.
• If another chat formatter plugin is installed, the output still uses the simple “<name> message” style and should look normal for players.
• ProtocolLib is optional; it only affects tab list appearances.

FAQ

• Q: Do I need ProtocolLib?
• A: No. It’s only required if you want fake players to appear in the tab list.

• Q: The AI doesn’t seem to reply sometimes—why?
• A: That’s intentional for realism. Increase chat.responseChance or enable debug to see the roll and decision logic.

• Q: Is the AI always online?
• A: If your provider keys are set and reachable, yes. If it fails, the plugin automatically falls back to a built-in text generator to keep things natural.

• Q: Can I use a different AI provider?
• A: Yes. Set ai.baseUrl, ai.model, and ai.apiKey for any OpenAI-compatible endpoint.

• Q: How do I reset or change fake names?
• A: Edit fakePlayers.names and /aiplayers reload.

Support

• Turn on debug.enabled and check your server console/logs for details.
• Verify your baseUrl, model, and apiKey are correct with your provider.
• Ensure outbound HTTPS is not blocked by your host or firewall.
• If tab isn’t working, install ProtocolLib (optional) and restart.

Changelog (high level)

• AI replies with external provider + fallback.
• Fake joins/leaves with random session durations.
• Optional tab list entries via ProtocolLib (auto-detected).
• Configurable debug logs for AI and simulation.