Arras Community Edition

⚠️ Beta Warning
Arras Community Edition is beta software. This build is not representative of the final product. Expect bugs, breaking changes, and incomplete features.

---

📌 Fork Notice

This project is forked from:
https://github.com/AE0hello/open-source-arras/

---

📚 Table of Contents

• 🎮 About
• ✨ Features
• 📋 Requirements
• 🚀 Quick Start (Localhost)
• 🐳 Docker (Local Development)
• 📁 Project Structure
• ⚙️ Configuration
• 🔐 Environment Variables
• 🌐 Server Travel (Nexus)
• 🧩 Addons
• 🗺 Rooms & Maps
• 🤖 Bots & AI
• 🛡 Administration & Moderation
• 🔧 Development Tips
• 🛠 Troubleshooting
• 🤝 Contributing
• 📄 License
• 👥 Community

---

🎮 About

Arras Community Edition is a self-hostable multiplayer Arras game server with a web client.

It provides:

• Integrated web client server (http://localhost:3000)
• Multi-instance real-time game servers (3001+)
• Modding framework (definitions, addons, room systems)
• Multi-server travel (Nexus portals)
• Docker support

---

✨ Features

• Web client hosted by the same Node process
• Room system with configurable maps and modes
• Entity definitions and addon hooks for modding
• Travel between servers via Nexus portals
• Dockerfile for local containers

---

📋 Requirements

• Node.js 18+
• npm

Verify installation:

node -v
npm -v

---

🚀 Quick Start (Localhost)

Install dependencies:

npm install

Start the server:

Windows:

run.bat

macOS / Linux:

./run.sh

Alternative:

npm start

Open the client:

http://localhost:3000

If you see Package 'ws' is not installed, run:

npm install ws

---

🐳 Docker (Local Development)

Build image:

docker build -t arras-ce .

Run with live file sync:

docker run -d --name arras \
  -p 3000-3020:3000-3020 \
  -v "$(pwd):/usr/src/app" \
  arras-ce

Stop / Remove:

docker stop arras
docker rm arras

Without volume mounting, rebuild the image after code changes.

---

☁️ GitHub Codespaces

This repo now includes a Codespaces devcontainer at devcontainer/devcontainer.json. Rename it to .devcontainer (It's named devcontainer currently to prevent issues with CodeSandbox)

Quick setup:

npm start

Then open the forwarded 3000 port in Codespaces.

Important:

• Codespaces is suitable for development and temporary testing
• This project uses many ports (3000 to 3020)
• Codespaces assigns separate public URLs per forwarded port
• Because of that, Codespaces is not the best production host for this repo's current networking model

For a practical public deployment, use a VPS with Docker and a domain. Full instructions are in docs/codespaces-and-hosting.md.

---

📁 Project Structure

Path	Description
server/server.js	Main server entry
server/config.js	Core configuration
server/.env	Tokens and API keys
server/Game/	Game logic
server/lib/definitions/	Entity definitions
server/Game/addons/	Gameplay addons
server/Game/room_setup/	Maps and room layouts
public/	Web client assets

---

⚙️ Configuration

All primary settings are in:

server/config.js

🎯 Skill Point Algorithm

Controls how many skill points players earn per level:

level_skill_algorithm: "arras", // or "improved"

Mode	Behavior	Total at level 45
"arras" (default)	1 point/level for levels 2–40, then 1 point every 2 levels (41, 43, 45)	42 points
"improved"	1 point per level for levels 2–45	44 points

Set in server/config.js.

---

🌐 Web Server Settings

host: "localhost:3000",
port: 3000,
allow_ACAO: true

🕹 Game Server Setup

Example configuration:

servers: [
  {
    share_client_server: false,
    host: "localhost:3001",
    port: 3001,
    id: "ffa",
    featured: false,
    region: "local",
    gamemode: ["ffa"],
    player_cap: 80,
    properties: {
      bot_cap: 16
    }
  }
]

Notes:

• gamemode references files from server/Game/gamemodeconfigs/
• properties override global config values
• player_cap affects server capacity and UI display

---

🔐 Environment Variables

Location:

server/.env

Common production setup:

PUBLIC_HOST=yourdomain.com
PORT=3000
GAME_HOST=yourdomain.com
GAME_PORT_BASE=3001
API_KEY=your_secret_key

Additional notes:

• PUBLIC_HOST affects client connections and share links.
• GAME_PORT_BASE defines the first port in your game server range.

---

🌐 Server Travel (Nexus)

Enable on destination server:

ALLOW_SERVER_TRAVEL: true

Configure source server:

SERVER_TRAVEL_PROPERTIES: {
  LOOP_INTERVAL: 10000,
  AMOUNT: 1
},
SERVER_TRAVEL: [
  {
    IP: "localhost:3002",
    PORTAL_PROPERTIES: {
      SPAWN_CHANCE: 3,
      COLOR: "red"
    }
  }
]

---

🧩 Addons

Gameplay Addons:

Path:

server/Game/addons/

Example:

module.exports = ({ Events, Config }) => {
  Events.on("chatMessage", () => {});
};

Entity Addons:

Path:

server/lib/definitions/entityAddons/

Example:

module.exports = ({ Class }) => {
  Class.customTank = {};
};

---

🗺 Rooms & Maps

Directory:

server/Game/room_setup/

Add a new map:

• Create room file in rooms/
• Use tiles from tiles/
• Assign the room in the gamemode config

---

🤖 Bots & AI

Controllers:

server/miscFiles/controllers.js

Default bot definition:

server/lib/definitions/groups/misc.js

Behavior tuning:

server/config.js

---

🛡 Administration & Moderation

Permissions file:

server/permissions.js

Chat commands:

server/Game/addons/chatCommands.js

Tokens are managed in:

server/.env

---

🔧 Development Tips

• Definitions and addons hot-reload on restart, so keep run scripts handy.
• When testing new servers, increment id values and ports to avoid conflicts.
• For local multiplayer testing, open multiple browser windows or profiles.

---

🛠 Troubleshooting

Problem	Fix
ws package missing	npm install ws
Port already in use	Change Config.port
Client loads but no servers	Check Config.servers
Server travel broken	Verify API_KEY and flags

---

🤝 Contributing

Workflow:

• Fork the repository
• Create a feature branch
• Commit focused changes
• Submit a pull request
• Include repro steps or screenshots for gameplay/UI changes

Contributors

Greninja9257 💻 🚧

All Contributors 🔧

DenisC 🐛

---

📄 License

This project uses the PolyForm Noncommercial License 1.0.0.
See LICENSE for full text.

---

👥 Community

Discord:
https://discord.gg/arras