A complete Ninja Saga private server framework including database, custom client, QOL management tools, Live PvP, live chat, clan/crew systems, and an expanded admin panel for managing game data without modifying code.

Recommended for most users

• ✅ tested
• 🔒 Only updated with verified and stable features

Use this branch if you want the most reliable version of the project.

Latest features, but not always stable

• 🧩 Contains new features and experiments
• ⚠️ May include bugs or breaking changes
• 🔄 Updated frequently

Use this branch if you want to test new functionality or contribute to development.

• Laragon (includes Apache, MySQL, PHP)
• PHP 8.4+
• Composer
• Node.js 18+ and npm
• Git

Download and install Laragon. The default install path is C:\laragon.

Start Laragon and make sure Apache and MySQL are both running.

Copy the Database/Laragon/ninjasage folder into Laragon's web root:

C:\laragon\www\ninjasage\

Your folder structure should look like:

C:\laragon\www\ninjasage\
  app\
  config\
  database\
  public\
  chat-server\
  pvp-server\
  ...

Copy the config files from Database/apache2 sites/ into Laragon's Apache vhosts folder:

C:\laragon\etc\apache2\sites-enabled\

Files to copy:

• 00-default.conf
• auto.ninjasage.test.conf
• clan.ninjasage.id.conf
• crew.ninjasage.id.conf

The clan and crew vhosts use per-domain SSL certificates included in the repo. Copy all four files from Database/etc/ssl/ into Laragon's SSL folder:

C:\laragon\etc\ssl\

Files to copy:

• clan.ninjasage.id.pem
• clan.ninjasage.id-key.pem
• crew.ninjasage.id.pem
• crew.ninjasage.id-key.pem

Then enable SSL: in the Laragon window, right-click the Apache entry and select SSL → Enable. Laragon will restart Apache automatically.

Error: Cannot access directory .../ninjasage/logs/

Apache requires the log directory to exist before it will start. Create it manually:

C:\laragon\www\ninjasage\logs\

Open C:\Windows\System32\drivers\etc\hosts as Administrator and add these lines:

127.0.0.1 ninjasage.test       #laragon magic!
127.0.0.1 clan.ninjasage.id
127.0.0.1 crew.ninjasage.id

Without these entries, the virtual host domains will not resolve on your machine.

The main site will be available at: https://ninjasage.test

Inside C:\laragon\www\ninjasage\, copy the example env file and edit it:

cp .env.example .env

Open .env and set your database credentials:

APP_NAME=NinjaSage
APP_URL=https://ninjasage.test

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ninjasage
DB_USERNAME=root
DB_PASSWORD=

CHAT_ADMIN_SECRET=your_secret_here

By default Laragon's MySQL uses root with no password.

PHP version: Make sure Laragon is using PHP 8.4 or later. You can switch PHP versions from the Laragon tray menu.

In the Laragon window, click Start All to start Apache and MySQL before continuing.

Open a terminal in C:\laragon\www\ninjasage\ and run:

composer install
php artisan key:generate

If you see this error:

Your lock file does not contain a compatible set of packages. Please run composer update.

A required PHP extension is likely disabled. The most common fix is enabling the zip extension:

1. Open your active php.ini. It will be something like:

   C:\laragon\bin\php\php-8.4.x-Win32-vs17-x64\php.ini
   

2. Find the line:

   ;extension=zip
   

3. Remove the semicolon so it reads:

   extension=zip
   

4. Save the file and restart Laragon (or reload PHP from the tray menu).
5. Run composer install again.

Create the database using the Laragon terminal:

mysql -u root -e "CREATE DATABASE ninjasage;"

Then run the migrations and seed the initial data:

php artisan migrate
php artisan db:seed

Once complete, verify the admin panel is working by visiting:

https://ninjasage.test/admin/login

Default credentials:

Open a new terminal and navigate into the chat server folder:

cd C:\laragon\www\ninjasage\chat-server
npm install

Copy the example env file and edit it:

cp .env.example .env

PORT=3002
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=ninjasage
DB_USER=root
DB_PASS=
CHAT_ADMIN_SECRET=your_secret_here

CHAT_ADMIN_SECRET must match the value you set in the Laravel .env.

Start the chat server:

npm start

You should see:

> [email protected] start
> node index.js

[Chat] Flash socket policy server listening on port 843
[MessageStore] chat_messages table ready
[Chat] Socket.IO server listening on port 3002
[Chat] Namespaces: /global-chat, /clan-chat

Open another new terminal and navigate into the PvP server folder:

cd C:\laragon\www\ninjasage\pvp-server
npm install

Copy the example env file and edit it:

cp .env.example .env

PORT=3000
DB_HOST=127.0.0.1
DB_PORT=3306
DB_NAME=ninjasage
DB_USER=root
DB_PASS=

Start the PvP server:

npm start

You should see:

> [email protected] start
> node index.js

[SkillData] loaded 1158 skills, 833 skill-effect entries
[PVP] Socket.IO server listening on port 3000
[PVP] Namespace: /pvp
[PVP] Turn duration: 30s
[PVP] Max rounds: 50

The chat and PvP servers are optional — the main server works without them, but those features will not be functional.

You need three things running at the same time:

Run NSCUSTOM.exe from Custom Client/NS Custom Client V1/.

Default game login:

To manage accounts, items, skills, and other game data, use the admin panel:

https://ninjasage.test/admin

To rebuild or patch the client, use the Python tools in the QoL Tools/ folder:

• CustomClientBuilder.py — builds the client package
• ninjasage_patcher.py — patches the SWF to point to your server
• gamedata_converter.py — converts game data files

Open a terminal in the server folder and run php artisan tinker to interact with the database directly.

See Database/Laragon/ninjasage/Documentation/Commands.txt for example commands to add items, skills, pets, and more to characters.

You can replay Ninja exams by setting your character level to one of the following:

Tip: Set your level to the corresponding value to unlock and replay the exam of your choice.