Introduction

Overview

Welcome to the documentation of Octet. This project aims to provide a versatile and feature-rich platform for running a private Yogurting Game Server.

Key Features

Compatible with Quartet XML Score files while expanding schema’s capabilities
Restores some of the game’s features (E.g. Friends, Calls)
Cross-platform compatibility
Enhanced security
Partial episode support
API interface, mainly for creating accounts
Command Console

Target Audience

Octet is dedicated to those who share a common goal – revisited a cherished game that was unfortunately discontinued. Whether you’re a passionate game enthusiast yearning for the nostalgia of the past, a server administrator seeking a more capable solution, you’re in a right place.

For the Game’s Enthusiasts, this is an opportunity to reconnect with the world they once loved. Server Administrators can easily migrate from Quartet to Octet, benefitting from its features, and make players love the same, but freshened gameplay ideas.

Documentation Purpose

This documentation serves as a comprehensive guide to help you understand, install, and configure Octet Game Server. Whether you’re a first-time user or an experienced server operator, this documentation will assist you in making the most of Octet.

Getting Started

Windows

Java Installation

Java installation

Since Octet was written in Java, Java 17 Runtime Environment or a higher version is required. The latest version of OpenJDK is recommended. Download OpenJDK here

After downloading, unzip the contents to a folder that suits you, such as C:\Program Files\openjdk.

Adding Java to PATH

To use Java from the command line or terminal, you need to add the Java bin directory to your system’s PATH variable. Here’s how to do it:

Open System Properties: Right-click on “This PC” or “My Computer” and select “Properties”. Then, click on “Advanced system settings” on the left sidebar.
Open Environment Variables: In the System Properties window, click on the “Environment Variables” button.
Edit PATH Variable: In the Environment Variables window, find the “Path” variable in the “System variables” section and select it. Then, click on the “Edit” button.
Add Java Bin Directory: In the Edit Environment Variable window, click on the "New" button and provide path to OpenJDK's bin directory. For version 22.0.1, it will be `C:\Program Files\openjdk\jdk-22.0.1\bin`, but for other versions of OpenJDK, the folder will be named differently. Click “OK” to save the changes.
Add JAVA_HOME Variable: In the Environment Variables window, click on the “New” button in the “System variables” section. Enter JAVA_HOME as the variable name and enter path to the Java installation directory as the variable value. Click “OK” to save the changes.
Verify Installation: Open a new command prompt or terminal window and type java -version. If Java is correctly added to the PATH, it should display the Java version information.

MySQL Installation & Configuration

Octet utilizes MySQL Database Management System (DBMS) to store players’ data. Its installation and configuration are required for Octet to run. Get MySQL Community Edition from here.

The installer will start by asking you what components you want to install. The server only option is recommended, but you can install components such as Workbench if you want.

config

After installation, the configuration process begins. It’s worth to set the configuration type to Server Computer. You can also change the port number, but you will have to reflect the change in db-host.

config

You need to use the Strong Password Encryption method for authentication:

config

Set a password for the root account.

config

It’s also worth to create a separate account for Octet. If the MySQL server will be hosted on the same computer as Octet, use the localhost option in the host field. This will prevent any connection from outside the host machine. However, if the database will be hosted elsewhere, select <All Hosts (%)>. With the provided password, Octet will log in to the database and write player data there.

config

Windows service settings are best left as they are. Changing them may cause errors in the next step.

config

If all the boxes are ticked off, congratulations. MySQL has been configured correctly and is already running on your system.

Linux (Debian-based)

Java Installation

Java installation

Since Octet was written in Java, Java 17 Runtime Environment or a higher version is required. I recommend using the latest version of OpenJDK 17. Here’s how to install it on Linux based on Debian distribution:

Java installation

1sudo apt update && sudo apt install openjdk-17-jre

MariaDB Installation

Octet utilizes MySQL Database Management System (DBMS) to store players’ data. Its installation and configuration are required for Octet to run. My recommendation for a Debian-based Linux is to use MariaDB:

MariaDB (MySQL) installation

1sudo apt install mariadb-server
2sudo mysql_secure_installation

MariaDB Configuration

It’s worth creating a new user dedicated to Octet. The example assumes that new user octet can connect from localhost and his password is secret.

⚠️ Notice: Remember to change the login credentials and hostname if the database will run on a different computer than the one Octet will be running on.

After creating a user, you need to grant him permissions. Then, flush privileges to make sure they got saved.

That completes the configuration of a database server for Octet.

MariaDB User creation

1sudo mariadb
2CREATE USER 'octet'@'localhost' IDENTIFIED BY 'secret';
3GRANT ALL ON *.* TO 'octet'@'localhost';
4FLUSH PRIVILEGES;

Running Octet

Now, it’s time to download Octet on your machine. Grab a release from here.

Extract the archive to a desired folder and run:

java -jar octet.jar

Run Octet

1java -jar octet.jar

Configuration

If Octet does not load the configuration file correctly, for instance when the file does not exist, it will generate a new default file and ask the user whether he wants to use the configuration wizard that will guide him through the setup process.

All available settings are described below.

IP

Hostname that Octet binds to. Accepts IPv4 and domain names.

Example: IP=127.0.0.1, IP=example.com

db-host

Hostname of the MySQL database. If your MySQL server is configured to run on a port other than the default, you can specify the port number after the hostname by separating them with a colon (:) symbol.

Example: `db-host=127.0.0.1` `db-host=127.0.0.1:1234`

db-username

Username used to login to MySQL database.

Example: db-username=octet

db-password

Password used to authenticate the user in MySQL database.

Example: db-password=secret

db-name

The name of the MySQL database to which Octet will connect and store data.

Example: db-name=octet_db

save-interval

The time in seconds after which Octet will write data to the database.

Example: save-interval=600

whitelist-only

Allows to join the server only by members of a whitelisted permission group.

true - enable whitelist false - allow every permission group to join.

Example: whitelist-only=false

log-global-chat

Prints global chat to the console and writes it to a file when enabled

Example: log-global-chat=true

check-for-updates

Checks at startup if a new version of Octet is available.

Example: check-for-updates=true

developer-mode

Watches the resources/score folder for changes and triggers a reload when detected. Useful for creating server’s Score.

Example: developer-mode=false

enable-api

Host API, used for various integrations such as a way to create accounts using private server’s website.

Example: enable-api=true

api-port

API’s port number.

Example: api-port=7000

enforce-verified

This setting, if enabled, allows only verified players to join. For more information, see API.

Example: enforce-verified=true

school-port

Port number of game’s School port. Handles most of the game data, events, actions.

Example: school-port=10002

comm-port

Port number of game’s Communication port. Handles social features like phone calls or friends.

Example: comm-port=10004

field-cache

FieldCache is a feature utilizing Java’s Serializable interface to create a cache of DB and XML Score files, shortening amount of time needed to load them. true enables FieldCache, false loads DB and XML files the normal way.

Example: field-cache=true

language

Set Octet’s CLI language. Available languages are en, ja, kr, th.

Example: language=en

world-name

A world name displayed when creating a character, logging into a server etc.

Example: world-name=OctetWorld

draw-distance-multiplier

Multiplier for sending information about nearby players and monsters. The higher, the greater the distance from which another player or monster can be spotted.

Example: draw-distance-multiplier=5

base-hp-increment

The base amount of life points added when a character levels up.

Example: base-hp-increment=7

Score

Score is the common name for files that define the content of game locations, called “Fields” using XML files. Octet reuses Quartet’s XML schema to ensure compatibility of existing scripts.

Folders containing score files must be located within the resources folder. Each score file should be placed in a subfolder named after the respective field code. To find the field codes, refer to the Field.txt file located in the resources/db folder.

Here are the cultivatable fields categorized by their prefixes:

- School Fields: Prefixed with “SF”
- Hunting Fields: Prefixed with “HF”
- Lobby Fields: Prefixed with “LW”

For example, to define the Estiva Ground Field, create a folder titled SF001001 in the score directory. You can now place XML files in this folder to define Field’s score. XML files can have any name. It’s a good practice to have a default XML file detailing objects like warpgates, hairdressers, lockers etc and separate XML Files for each NPC intended for this field.

Sample scheme:

 1└── resources
 2    └── score
 3        └── SF001001
 4            ├── default.xml
 5            ├── npc_anna.xml
 6            ├── npc_mocha.xml
 7            ├── npc_suchon.xml
 8            ├── npc_ben.xml
 9            ├── npc_peko.xml
10            ├── npc_no1.xml
11            └── npc_no2.xml

A Score file should adhere to the following structure:

1<?xml version="1.0" encoding="UTF-8"?>
2<field>
3    <!-- Score content here -->
4</field>

Within the field tags, you’ll include the content relevant to your score. The nodes you can use are described below.

warpgate

Warpgate is an object that allows players to move between Fields.

Attributes

id int
Identification number. Must be unique.
x int
X Position. Actual coordinates multiplied by 100.
y int
Y Position. Actual coordinates multiplied by 100.
shell int
Appearance.
idCli int
Unknown. It is best to use the one provided in the default XML.
dir int
Direction.
idDestField int
Destination field’s identification number. Refer to Field.txt to obtain field IDs.
xDest int
X coordinates to which the player will be moved.
yDest int
Y coordinates to which the player will be moved.

Warpgate example

<warpgate id="1" x="7590" y="11499" shell="78" idCli="818" dir="0" idDestField="2" xDest="66" yDest="103"/>

episodegate

Episode Gate is an entry point for players into episodes. They can create an episode waiting rooms and then play episodes within them.

Attributes

subid int
EpisodeGate ID. Best not to modify.
idCli int
Unknown. It is best to use the one provided in the default XML.
shell int
Appearance.
x int
X Position.
y int
Y Position.
dir int
Direction.
visible boolean
Set visibility.
usable boolean
Set if can be used or not.

Episode

Determine episodes available to play in EpisodeGate.

Attributes

id int
Episode ID. Refer to Episode.txt.
grade int
Grade required to play an episode.

Episode gate example

<episodegate subid="10001" idCli="543" shell="82" x="61" y="98" dir="0" visible="1" usable="1">

<episode id="1" grade="1" name="Wizard of Oz"/>

</episodegate>

vmachine

Create a capsule machine. Used by players to draw dancing CoItems.

Attributes

totalAmount int
Number of capsules held.
price int
Price for each item draw.
subid int
Unknown. Best not to modify.
idCli int
Unknown. It is best to use the one provided in the default XML.
shell int
Appearance.
x int
X Position.
y int
Y Position.
dir int
Direction.
visible boolean
Set visibility.
usable boolean
Set if can be used or not.

Product

Identify the products available to draw from the vending machine.

Attributes

type int
Specify the consumable item type. Refer to CoItemType.txt
amount int
Quantity given to player
secret boolean
Hide the item icon.

Vending machine example

<vmachine totalAmount="100" price="100" subid="101" idCli="142" shell="87" x="28" y="17" dir="0" visible="1" usable="1">

<product type="60001" amount="10" secret="false"/>

<product type="60010" amount="3" secret="false"/>

<product type="60019" amount="2" secret="true"/>

</vmachine>

locker

Players can store items in lockers.

Attributes

subid int
Unknown. It is best to use the one provided in the default XML.
idCli int
Unknown. It is best to use the one provided in the default XML.
shell int
Appearance.
x int
X Position.
y int
Y Position.
dir int
Direction.
visible boolean
Set visibility.
usable boolean
Set if can be used or not.

Locker example

<locker subid="137" idCli="137" shell="86" x="350" y="18" dir="6" visible="1" usable="1"/>

hairdresser

At the hairdresser, players can change appearance of their character, more specifically the color and their hairstyle.

Attributes

subid int
Unknown. It is best to use the one provided in the default XML.
idCli int
Unknown. It is best to use the one provided in the default XML.
shell int
Appearance.
x int
X Position.
y int
Y Position.
dir int
Direction.
visible boolean
Set visibility.
usable boolean
Set if can be used or not.

Hairdresser example

<hairdresser subid="356" idCli="356" shell="84" x="118" y="56" dir="4" visible="1" usable="1"/>

NPC

NPCs are the main foundation of Score. They control a huge chunk of the gameplay on the server.

1<npc id="365" shell="78" x="72" y="68" dir="6" init="init">
2<!-- NPC Content here -->
3</npc>
4

Attributes

id int
ID. Refer to NpcEx.txt to obtain IDs corresponding to specific NPCs.
shell int
NPC Appearance.
x int
X Position.
y int
Y Position.
dir int
Direction.
init string
Default label name. Enter the name of the dialog or script.

dialog

Define a conversation dialog.

Attributes

npcid int
NPC number, Optional. If not set, the NPC ID set in the <npc> node will be used. Useful when you want to display a CutIn image from a different NPCs.
name string
Label name. Has to be unique since it’s used to navigate through dialogs.
cutin int
NPC’s image. 0 by default, but you can provide an incremental number for NPCs that have more CutIns (1, 2, 3, etc.) You can set it as a variable.
timeout int
Time after which the dialog will be closed. Optional.
choiceontimeout int
Selection that will be selected upon timeout. Optional.
closebutton boolean
Controls the state of the dialog close button. true - on, false - off. Optional, close button is enabled by default.
bgframeclick boolean
Determine whether the dialog can be closed when you click on an area outside the dialog box. Optional, default is false.
Text
Dialog text. You can use text such as <br>, <font>, <b> or <i>. You can also use ${variables}. It is recommended to enclose the text in a CDATA section.

selection

selection defines the available options to respond to the NPC. You can add up to 3 selections.

Attributes

name string
Specify the label name for the next dialog, etc. If omitted, the dialog will end.
text string
Text of the answer. You can use ${variables}.
op string
Specify the process to be executed when selected. Optional. Available values:

set - Set variable’s value.

inc - Increment a variable by 1.

dec - Decrease a variable by -1.
varname string
Variable name used by the op process. Required if op is specified.
value string
Specify a value. ${variables} can be used. Required only if op is specified and set.

NPC Dialog example

1<dialog name="anna_1" cutin="0" closebutton="0">
2  <text><![CDATA[
3    Hello! I'm Anna! I'm very happy to meet you!
4    ]]></text>
5  <selection next="anna_2" text="Hello Anna!"/>
6</dialog>

buy

Display the item purchase screen.

Attributes

name string
Label name.

beitem

Define BeItems that will be available to buy.

Attributes

type string
BeItem ID. Refer to BeItemType.txt
price int
BeItem’s price.

coitem

Define CoItems that will be available to buy.

Attributes

type string
CoItem ID. Refer to CoItemType.txt
price int
CoItem’s price.

enitem

Define EnItems that will be available to buy.

Attributes

type string
EnItem ID. Refer to EnItemType.txt
price int
EnItem’s price.

NPC Buy

1<buy name="no2_buy">
2  <beitem type="110006" price="100" />
3  <coitem type="10001" price="50" />
4  <enitem type="10001" price="500" />
5</buy>

sell

Display the item sell screen.

Attributes

name string
Label name.

NPC Sell

<sell name = "sell"/>

crystal

Display the crystal purification screen.

Attributes

name string
Label name.

NPC Crystal

<crystal name = "crystal"/>

attachstone

Display the source stone mounting screen.

Attributes

name string
Label name.

NPC Attachstone

<attachstone name = "attach"/>

detachstone

Display the source stone detaching screen.

Attributes

name string
Label name.

NPC detachstone

<detachstone name = "detach"/>

breakstone

Display the source stone destruction screen.

Attributes

name string
Label name.

NPC breakstone

<breakstone name = "break"/>

buyskill

Display the skill purchase screen.

Attributes

name string
Label name.

skill

Define skills to be displayed on the skill purchase screen.

Attributes

type string
Skill ID. Refer to SkillDesc.txt.
price int
Skill’s price.

NPC Skill buy

<buyskill name = "skill_normal">

<skill type = "21001" price = "50"/>

</buyskill>

message

Display a message in the center of the screen.

Attributes

text string
Message content. ${variables} can be included.
altframe boolean
Use an alternative message frame. Optional.

NPC Message

<message text="Reach level 2!" altframe="true"/>

warp

Move the character to specified Field.

Attributes

name string
Warp name.
idDestField int
Destination Field ID.
xDest int
Destination X coordinates.
yDest int
Destination Y coordinates.

NPC Warp

<warp name="warp" idDestField="90" xDest="127" yDest="166"/>

bus

Play the bus cutscene and move player to specified coordinates.

Attributes

name string
Bus name.
school int
Specify the cutscene to display. 1 is for Estiva, 2 - Sowol.
idDestField int
Destination Field ID.
xDest int
Destination X coordinates.
yDest int
Destination Y coordinates.

NPC Bus

<bus name ="sowol_bus" school="2" idDestField="90" xDest="127" yDest="166"/>

Walkpath

Walkpath is a completely new feature that allows NPCs to move through the field. Available to every NPC except penguins. NPCs move according to the predefined path.

walkpath attributes:

interval string
The time after which the NPC will move again after a completed route. The time numeral is followed by a character indicating the time unit: s - second, m - minute, h - hour, d - day.
name string
Warp name.
idDestField int
Destination Field ID.
xDest int
Destination X coordinates.
yDest int
Destination Y coordinates.

pathpoint attributes:

x int
X coordinates of the point to which the NPC will head.
y int
Y coordinates of the point to which the NPC will head.
speed int
The speed at which the NPC will move to the specified point. The higher it is, the faster the movement will be.
cooldown string
The time after which the NPC will proceed to the next point. The time numeral is followed by a character indicating the time unit: s - second, m - minute, h - hour, d - day.

NPC Walkpath example

1<walkpath interval="18s">
2    <pathpoint x="87" y="98" speed="20" cooldown="2s"/>
3    <pathpoint x="64" y="95" speed="20" cooldown="10s"/>
4    <pathpoint x="125" y="113" speed="20" cooldown="25s"/>
5    <pathpoint x="94" y="105" speed="20" cooldown="10s"/>
6</walkpath>

Scripts

Declare scripts using variables and operators. Each script is executed sequentially from the top.

1<script name="mocha_script">
2<!-- Script content here -->
3</script>
4

Attributes

name string
Label name.

If operators

Thanks to if operators, actions can be performed if certain conditions are met.

Each <if> node can be followed by an <else> node that will be executed if the condition is not met.

Available if operators:

ifeq
Checks if given variable is equal to a provided value.
ifne
Checks if given variable is not equal to a provided value.
ifge
Checks if given variable is higher or equal to a provided value.
ifle
Checks if given variable is lower or equal to a provided value.
ifdef
Checks if given variable name is defined. Does not use varname attribute.
ifndef
Checks if given variable name is not defined. Does not use varname attribute.
ifbeitem
Checks if player has a specific BeItem in his inventory. Does not use varname attribute. Use BeItem’s ID in value.
ifcoitem
Checks if player has a specific CoItem in his inventory. Does not use varname attribute. Use CoItem’s ID in value.
ifenitem
Checks if player has a specific EnItem in his inventory. Does not use varname attribute. Use EnItem’s ID in value.
ifepi
Checks if player has cleared a specific episode. Does not use varname attribute. Use Episode’s ID in value.
ifnepi
Checks if player didn’t clear a specific episode yet. Does not use varname attribute. Use Episode’s ID in value.
ifpermgroup
Checks if player is a member of a specific permission group. Does not use varname attribute. Use Permission group name in value.
ifnpermgroup
Checks if player is not a member of a specific permission group. Does not use varname attribute. Use Permission group name in value.

Attributes

varname string
Variable you want to check the value against.
value string
Checked value.
amount int
Item amount to check against. Used optionally only in ifbeitem, ifcoitem, ifenitem.

Variable-based IF operator

1<script name="nana_schoolcheck">
2    <getcharinfo type="school" varname="player.school"/>
3    <ifeq varname="player.school" value="2">
4        <jump label="nana_sowol"/>
5    </ifeq>
6    <else>
7        <jump label="nana_estiva"/>
8    </else>
9</script>

Episode-based IF operator

1<script name="anna_episodecheck">
2	<ifepi value="76">
3        <jump label="anna_deliveryepisode_complete">
4    </ifepi>
5</script>

Items

It’s possible to add or remove players’ items.

At this point it is worth clarifying the naming of Items in the game:

BeItem
Items that players can wear, such as Blades, Spirits, and footwear.
CoItems
Items such as potions that can be used by players. An abbreviated form of Consumable Items.
EnItems
Items used for enchanting, mainly reference books. Abbreviated form of Enchantment Items.

Available item operations:

addbeitem
Gives player BeItem(s).
delbeitem
Removes BeItem(s).
addcoitem
Gives player CoItem(s).
delcoitem
Removes CoItem(s).
addenitem
Gives player EnItem(s).
delenitem
Removes EnItem(s).

Attributes

type int
Be/Co/En Item ID. You can use ${variables}.
amount int
Co/En Item only. Amount of times to obtain or delete. You can use ${variables}.
equip boolean
BeItem only. Makes the player equip obtained BeItem when true. Used only in onmakechar.

Item operations

1<addbeitem type="110001"/>
2<addcoitem type="10005" amount="3"/>
3<delcoitem type="10001" amount="15"/>

Variable operations

Available variable operations:

set
Set the variable to a value.
add
Add a value to the variable.
sub
Subtract a value from the variable.
mul
Multiply the variable by a value.
div
Divide the variable by a value.
mod
Get the remainder when divided by the value.
inc
Increment a variable by 1.
dec
Reduce the value of the variable by 1.
rnd
Assign a random value to a variable. For example, if 10 is specified as a value, a number from 0 to 9 will be returned.

Attributes

varname string
Variable name.
value string
The value used for the operation. Integers and ${variables} can be specified. Not used in inc and dec.

Variable Operations

1<set varname="visited.arena" value="true"/>
2<inc varname="player.arena.visitcount"/>

getcharinfo

Using getcharinfo allows you to assign player’s values to variables.

Attributes

varname string
Variable name.
type string
Specify the type of information to be acquired. Available types listed below.

Available getcharinfo types:

name string
Retrieves character name.
grade int
Retrieves character grade.
blood int
Character’s blood type from 1 to 4 where 1 is A and 4 is O.
taff int
Retrieves character’s TAFF amount.
school int
Character’s school. 1 - Estiva, 2 - Sowol.
sex int
Character’s gender. 1 - Male, 2 - Female.
level int
Character Level.
hp int
Character’s current HP.
maxhp int
Character’s maximum HP.
exp int
Character’s current XP.
maxexp int
Character’s maxmimum XP.
lang string
Returns player’s selected language.
permgroup string
Returns player’s permission group.

Getcharinfo example

1<getcharinfo varname="player.hp" type="hp"/>
2<getcharinfo varname="player.maxhp" type="maxhp"/>
3<ifle varname="player.hp" value="${player.maxhp}">
4    <jump label="inject_heal"/>
5</ifle>

setcharinfo

Using setcharinfo allows you to change player’s values to given values.

Attributes

type string
Character info type.
value string
Value of changed type.

Available setcharinfo types:

lang string
Set player’s language. Only supported language codes can be used.
grade int
Set character grade from 1 to 6.
taff int
Modify player’s TAFF.
hp int
Set character’s HP.
exp int
Set character’s XP.
permgroup string
Set character’s permission group.

Setcharinfo Example

1<setcharinfo type="taff" value="100"/>
2<setcharinfo type="hp" value="1"/>

getsysinfo

Using getsysinfo will retrieve server-based value and assign them to a variable.

Attributes

varname string
Variable name.
type string
Type of system information to retrieve.

Available getsysinfo types:

clock int
Get in-game time (0-3, 3 is night)
player int
Get connected players count.

Getsysinfo Example

1<getsysinfo varname="local.clock" type="clock"/>
2<getsysinfo varname="local.player" type="player"/>

setsysinfo

Using getsysinfo will change server-based values.

Attributes

type string
Server value type.
value string
Type of system information to change.

Available setsysinfo types:

clock int
Set in-game time (0-3, 3 is night)

Setsysinfo Example

1<setsysinfo type="clock" value="3"/>

getdatetime

getdatetime is used to get the server time.

Attributes

type string
Specify the type of date and time to retrieve.
varname string
Variable name.

Available getdateime options:

year
Retrieve year.
month
Retrieve month.
day
Retrieve day.
hour
Retrieve hour.
minute
retrieve minute.
second
Retrieve second.

Getdatetime Example

1<getdatetime type="month" varname="time.month"/>

Switch

A switch is a control statement that helps make decisions based on different conditions. It evaluates an expression and executes a block of code based on the value of an variable. It’s often used when you have multiple possible outcomes and need to choose one based on a specific condition.

Attributes

varname string
Variable name.

Case

Specify the values of a switch.

Attributes

value
The value that will be checked against the specified varname. It’s possible to use ${variables}.

Switch Example

1<switch varname="player.school">
2  <case value="1">
3    <jump label="ben_estiva"/>
4  </case>
5  <case value="2">
6    <jump label="ben_sowol"/>
7  </case>
8</switch>

call

Executes a specified library function.

Attributes

name string
Function name. ${variables} can be used. When referring to a function defined in a specific file, you need to include both the filename and the function name separated by a dot at the beginning of the name. For instance, if your function file in the lib folder is named system.xml and the function you want to call is named func, you’d use system.func.

Call Example

<call name="system.func"/>

jump

Jumps to the specified label name.

Attributes

label string
Label the script will jump to. ${variables} can be used. Available jump destinations are: dialogs, scripts, buy, sell, crystal, attachstone, detachstone, breakstone, buyskill, message, warp and bus.

Jump example

1    <ifeq varname="player.school" value="2">
2        <jump label="nana_sowol"/>
3    </ifeq>
4    <else>
5        <jump label="nana_estiva"/>
6    </else>

sysmsg

Sends a message displayed in chat to the player.

Attributes

text string
Message content.
global boolean
If this value is true, sends a message to each player. If false or omitted, only the related player will receive it.

sysmsg example

<sysmsg text="Display all available commands by typing /help in the chat./>

debug

Prints a text to Octet’s console.

Attributes

text string
Message content. It’s possible to include ${variables}.

debug example

<debug text="The current value is $ {temp}."/>

Playback

Score scripts can be used to trigger playback of BGM, sound effects and movie cutscenes for one or more players.

List of functions

bgm
Plays a background music (BGM).
se
Plays a sound effect (SE).
video
Plays a movie cutscene.

Attributes

value int
BGM/SE/Movie ID. ${variables} can be used.
target string
Optional attribute to affect other players. everyone will play specified media to each player on the server. field will play to every player in the same field as NPC.

playback example

<bgm value="19"/>

<video value="104" target="everyone"/>

save

Set player’s respawn position.

Attributes

field int
Field ID. Refer to Field.txt.
x int
X position.
y int
Y position.

save example

<save field="1" x="80 y="70"/>

Monsters

Monsters can only be spawned in hunt fields (fields with the HF prefix).

To do this, you need to determine the spawn points and then the type of monsters and how many of them are going to spawn. It needs to be wrapped in a generator tag.

spawn Attributes:

x int
X coordinate of monster spawner.
y int
Y coordinate of monster spawner.

monster Attributes:

type int
Monster ID. Refer to HuntMon.txt.
count int
The number of monsters that will be spawning across defined spawners.
active boolean
If true, monsters will attack the player as soon as they notice him.

Monster spawner

 1	<generator>
 2		<point x="34" y="36"/>
 3		<point x="43" y="36"/>
 4		<point x="38" y="50"/>
 5		<point x="36" y="63"/>
 6        
 7		<monster type="1" count="48" active="true"/>
 8		<monster type="2" count="68" active="true"/>
 9
10	</generator>

Library

Library score defines functions which are a set of script operations.

To create library score files, create an XML file in the resources/score/lib directory. The name of the file can be anything you want.

Sample scheme:

1resources
2└── score
3    └── lib
4        ├── system.xml
5        └── my-library.xml

A Library file should adhere to the following structure:

1<?xml version="1.0" encoding="UTF-8"?>
2<library>
3<!-- Library content here... -->
4</library>

Add your functions within the library tags:

1<?xml version="1.0" encoding="UTF-8"?>
2<library>
3    <function name="hello">
4        <getcharinfo type="name" varname="player.name"/>
5        <sysmsg text="Hello ${player.name}!"/>
6    </function>
7</library>

Use the same schema as for NPC scripts except for jump operation to program functions. Functions defined in library score can be called using the <call> tag inside the NPC script.

move

Move the character to specified Field. Works only in Library functions.

Attributes

field int
Destination Field ID.
xDest int
Destination X coordinates.
yDest int
Destination Y coordinates.

Move

<move field="90" xDest="127" yDest="166"/>

Mail Order

Mail Order, also called SpecialPhone, is a feature allowing players to call a number for an additional fee to purchase items delivered instantly to their inventory.

File that defines SpecialPhone should be located in resources/score and must be named SpecialPhone.xml to work properly.

SpecialPhone.xml should start and end with a node. Inside it, add NPCs, dialogs, and purchase menus in the same way you would when defining NPCs in Field Score.

You can add a maximum of 2 NPCs. The NPC first in order will be No. 2, the second one will be No. 27.

Commands

Octet has commands unified with chat and CLI. They allow to manage the server conveniently. Some of the commands use a special syntax to make the time specifying possible. Specify the time followed by a character indicating the time unit: s for seconds, m for minutes, h for hours, or d for days.

There are also commands that can be executed only by the console or only by players. The player executing the command must be a member of the permission group that allows that command to be executed.

In command descriptions, arguments surrounded by <inequality symbols> mean required arguments, and arguments surrounded in [square brackets] are optional.

Commands executed via chat must be entered with a prefix (/), e.g. /speed 3 20.

About

Checks current server and environment version.

Aliases: version Permission code: command.about

Stop

Saves players’ data and stops the server

Aliases: exit, quit Permission code: command.stop

Reload

Reload Score and permissions.

Permission code: command.reload

Field

Check current field information. Aliases: where Permission code: command.field

Account

💻 Console only

Manage accounts on the server

Subcommands:

create
Create an account on the server. A prompt to enter the password will appear after entering the command.
- Usage: account create <Account name>
delete
Delete an account from the server. A prompt to reconfirm deletion will appear after entering the command.
- Usage: account delete <Account name>

Permission code: command.account

Kick

Kick players from the server.

Syntax

`kick <Player>`

<Player>: The player you want to kick.

Permission code: command.kick

Mute

Disallow a player from sending chat messages.

Syntax

`mute <Player> [Time] [Reason]`

<Player>: The player you want to mute.
[Time] (Optional): The duration for which the player will be muted. Specify the time followed by a character indicating the time unit: s for seconds, m for minutes, h for hours, or d for days. If not specified, the mute is permanent.
[Reason] (Optional): The reason for muting the player.

Usage:

mute loudman53 1h Spamming chat

This command will mute loudman53 for 1 hour for spamming chat.

Permission code: command.mute

Ban

Disallow player to access the server.

If a player is banned, a message about a ban will be sent to each player via chat.

Syntax

`ban <Player> [Time] [Reason]`

<Player>: The player you want to mute.
[Time] (Optional): The duration for which the player will be banned. Specify the time followed by a character indicating the time unit: s for seconds, m for minutes, h for hours, or d for days. If not specified, the ban is permanent.
[Reason] (Optional): The reason for banning the player.

Usage:

ban funnyplayer 14d Use of prohibited software

This command will ban funnyplayer for 14 days for use of prohibited software.

Permission code: command.ban

Goto

💬 Chat only

Changes player’s location to the specified destination.

Syntax

`goto <Field ID> [X] [Y]`

<Field ID>: Determine the destination field you want to go to.
[X] (Optional): X coordinates you want to go to.
[Y]: Y coordinates.

Usage:

goto 92

Permission code: command.goto

Permission

Manage permission groups and assign them to players.

Syntax

perm player <Player> set <PermissionGroup>

<Player>: The player whose permission group you want to change.
<PermissionGroup>: The permission group to set for the player. Refer to permission-groups.yml.

Usage

perm player tastybacon set GM

This example will set tastybacon’s permission group to GM or GameMaster.

Permission code: command.permission

Aliases: perm

Level

Set player’s level.

Syntax

level [Level] [Player]

[Level]: Number from 1 to 300 representing the level. If not specified, level will increase by 1.
[Player]: Player who will be affected by the command. If not specified, that player will be the one executing the command. Required when executed by the console.

Example

level 42 brightstar987

Permission code: command.level

Time

Display or set current game time.

Syntax

time get

This command retrieves the current server time.

time set <number>

Sets the server time to the specified value.

<number>: The time value to set. It must be a number from 0 to 3 where 3 is night.

Permission code: command.time

Back

💬 Chat only

Moves player to his previous location or to a saved location.

Syntax

back [Memo]

[Memo] (Optional): Saved location, number from 0-9. For more information, see Memo.

Permission code: command.back

Memo

💬 Chat only

Saves current position under specified number from 0-9. Use back to move to the saved location.

Syntax

memo <Index>

<Index>: Index of stored location from 0 to 9.

Permission code: command.memo

Language

💬 Chat only

Set and display available languages.

Syntax

language [LanguageCode]

[LanguageCode] (Optional): The language code to set the server’s language. If not provided, prints available languages.

Permission code: command.language

Aliases: lang

Save

💬 Chat only

Performs data writing of the player executing the command to the database.

Permission code: command.save

Save-all

Writes each player’s data to the database.

Permission code: command.saveall

Speed

💬 Chat only

Changes issuer’s attack/movement speed.

Syntax

speed [AttackSpeed] [MovementSpeed]

[AttackSpeed] (Optional): The attack speed number to set.
[MovementSpeed] (Optional): The movement speed number to set. If both arguments are not provided, default speed will be set.

Permission code: command.speed

Charge

💬 Chat only

Charges issuer’s skill bar.

Permission code: command.charge

Beitem

Gives player a specific BeItem

Syntax

beitem <BeItem ID> [Player]

<BeItem ID>: The ID of the item to be given.
[Player] (Optional): The player to whom the item will be given. Required when executing from the console.

Permission code: command.beitem

Coitem

Gives player a specific CoItem

Syntax

coitem <CoItem ID> [Amount] [Player]

<CoItem ID>: The ID of the item to be given.
[Amount] (Optional): Number of items that will be given.
[Player] (Optional): The player to whom the item will be given. Required when executing from the console.

Permission code: command.coitem

Enitem

Gives player a specific EnItem

Syntax

enitem <EnItem ID> [Amount] [Player]

<EnItem ID>: The ID of the item to be given.
[Amount] (Optional): Number of items that will be given.
[Player] (Optional): The player to whom the item will be given. Required when executing from the console.

Permission code: command.enitem

Announce

Announces an message to all players.

Syntax

announce <Text>

<Text>: Announcement content. Before sending, the command checks whether a message with this name exists in announce-schedule.yml file. If it exists, a message from that file will be sent. If not, the typed text will be sent.

Permission code: command.announce

Whitelist

Whitelist is a feature that allows you to restrict access to the server only for particular permission groups. The whitelist command is used to manage whitelist status.

Syntax

whitelist [boolean]

[boolean] (Optional): Enables whitelist if true, disables the whitelist if false. If not provided, shows current whitelist status.

Permission code: command.whitelist

Chat

Manage current chat settings.

Syntax

chat <disable|enable>

chat <disable|enable>: Disables or enables the entire chat functionality.

Permission code: command.chat

Variable

Modify variables within your character

Syntax

<VarName>: The name of the variable.
<Value>: The value to set for the variable (only used with set command).

Sub-Commands

`set`

Set the value of a variable.

Syntax

var set <Varname> <Value>

`get`

Retrieve the value of a variable.

Syntax

var get <Varname>

`del`

Delete a variable.

Syntax

var del

Aliases: variable Permission code: command.variable

Unmute

Cancels muted player’s penalty.

Syntax

unmute <Player>

<Player>: The player you want to unmute.

Permission code: command.unmute

Unban

Cancels banned player’s penalty.

Syntax

unban <Player>

<Player>: The player you want to unban.

Permission code: command.unban

Spawn

Spawns a monster in the hunt field.

Syntax

spawn <MonsterID> [FieldID] [X] [Y]

<MonsterID>: The ID of the monster to spawn.
[FieldID] (Optional): The ID of the field where the monster will spawn. Required when executing from console.
[X] (Optional): The X-coordinate of the spawn location.
[Y] (Optional): The Y-coordinate of the spawn location.

If no arguments are provided, the monster will spawn in a random coordinates in the same field of the issuer if the field is hunt field.

Permission code: command.spawn

Playercount

Show current player count.

Syntax

playercount [FieldID]

[FieldID] (Optional): The ID of the field for which to display the player count. If not provided, shows the total player count on the server.

Aliases: pc Permission code: command.playercount

Update

Check for updates and perform updates if available.

Syntax

update [perform]

[perform] (Optional): If an update is found, allows performing the update process.

Permission code: command.update

TAFF

Add or subtract TAFF (currency) from a player.

Syntax

TAFF <Amount> [Player]

<Amount>: The amount of TAFF to add or subtract.
[Player] (Optional): The player whose TAFF will be modified. Required when running from console.

Permission code: command.taff

Ban IP

Ban the IP address of a player.

Syntax

banip <Player>

<Player>: The player whose IP address will be banned.

Permission code: command.banip

Unban IP

Unban the IP address of a player.

Syntax

unbanip <Player>

<Player>: The player whose IP address will be unbanned.

Permission code: command.unbanip

Grade

Set player’s grade.

Syntax

grade [Value] [Player]

[Number]: The grade value from 1-6 to assign to the player.
[Player]: The player to whom the grade will be assigned. Required when running from console.

Permission code: command.grade

Charname

💬 Chat only

Allow a player to change their character name. The player will see the change only after re-logging.

Syntax

charname <Player> <NewName>

<Player>: Targeted player.
<NewName>: The new character name the player wishes to change to.

Aliases: name

Permission code: command.charname

API

💻 Console only

Manage API keys and API status.

Syntax

api keys

api status

api start

api stop

api addkey <Name> [Timestamp]

api delkey <Name>

api showkey <Name>

keys: Show a list of API keys.
status: Check the API status.
start: Start the API.
stop: Stop the API.
addkey <Name> [Timestamp]: Add an API key with an optional expiry timestamp. Timestamp format: yyyy-mm-ddThh:mm:ss
delkey <Name>: Delete an API key.
showkey <Name>: Show details of a specific API key.

Permission code: command.api

Permission Groups

Permission groups are a system that determines what commands can be executed by players. Players’ privileges are defined by the permission group they belong to.

By default, there are 3 permission groups:

GameMaster (GM)
Otherwise known as the server administrator. He can manage items, TAFF, or the server itself.
Communnity Manager (CM)
Community Managers moderate players’ behavior and issue punishments in case of prohibited actions.
Player
Default permission group of each player. Enables basic commands.

When running Octet in developer mode, the GM group is given an attack speed of 3 and a movement speed of 20 when joining the server.

Permission file

In the permission file you can add new permission groups and change the access to commands that each group has.

The file is located in resources/permission-groups.yml.

Adding a New Permission Group

To add a new permission group to your server, follow these steps:

Open the Permission Groups Configuration File: Locate and open the YAML file where the permission groups are defined. The file is located in resources/permission-groups.yml.
Define the New Permission Group: Inside the file, add a new section for the permission group you want to create. The section should include the following information:
- Group Name: The name of the permission group.
- Description: A brief description of the permission group.
- Default: Whether the group should be assigned to new players by default.
- Whitelisted: Whether the group is whitelisted (only specific players can join).
- Permissions: A list of permissions granted to this group. Permissions control what actions members of this group can perform. Refer to commands section to obtain permission codes for each command.
Save the Changes: Save the changes you made.

Example

Suppose you want to add a new permission group named “Regular Player” with the following characteristics:

Description: This is a default Regular Player permission group.
Default: true (assigned to new players by default).
Whitelisted: false.
Permissions:
- chat.read: Allow members to read chat messages.
- chat.send: Allow members to send chat messages.
- command.about: Allow members to view information about the server.
- game.*: Allow members to access all game actions.

Your entry in the permission-groups.yml file would look like this:

1RegularPlayer:
2  description: This is a default Regular Player permission group.
3  default: true
4  whitelisted: false
5  permissions:
6    - chat.read
7    - chat.send
8    - command.about
9    - game.*

Announce schedule

Announce schedule is a feature that allows you to broadcast messages to every player on the server in multiple languages.

Announce file

In announce-schedule.yml located in the resources folder, you can set custom messages and their broadcast interval.

Adding Entries to Announce Schedule

To add new announcements to your announce schedule, open announce-schedule.yml and add a new section for the announcement you want to create. The section should include the following information:

Event Name: A unique identifier for the announcement.
Interval: The time interval between each announcement. Specify the time followed by a character indicating the time unit: s for seconds, m for minutes, h for hours, or d for days. It is also possible to specify a zero time value, such as 0s so that it can only be announced with the announce command.
Text: Key for the message content. Each translation is denoted by a language code (`ja` for Japanese, `kr` for Korean, and `en` for English) followed by a colon (:), and then the corresponding message content.

Save the Changes: Save the changes you made.

Example

Suppose you want to add a new announcement named “New Announcement” with the following characteristics:

Interval: Every 1 hour.
Text: “This is a new announcement.”

Your entry in the configuration file would look like this:

1new-announcement:
2  interval: 1h
3  text:
4    ja: これは新しいお知らせです。
5    kr: 이것은 새로운 공지입니다.
6    en: This is a new announcement.

API

Octet has an API designed to be integrated with a private game server website to create accounts using a registration form.

Authentication

The server authenticates API requests using the Authorization Bearer method. When making an API request, the request header should include the following:

Content-Type: This specifies the media type(s) that are sent in the request. It should be set to application/json.
Authorization: This header field contains the authentication credentials for the request. In the Bearer method, the value should be prefixed with the word "Bearer" followed by a space and then the token. For example: Authorization: Bearer <Token>. The <Token> represents the authentication token that is generated using the api command.

/accounts

The accounts POST endpoint is used to manage accounts.

Request Body

The request body should be in JSON format and include the following fields:

Required Fields:
- username: The username of the new account. It should be at least 3 characters long.
- password: The password of the new account. It should be at least 5 characters long.
- lang: The preferred language of the user.
Optional Fields:
- email: The email address of the user. If specified, a verification code will be generated and sent back.
- verified: A boolean value indicating whether the new account should be automatically verified if true.

Response

Success Response: If the account is successfully created, a 201 Created response is returned.
Error Response: If there are any validation errors or if the request fails for any reason, an appropriate error response with the corresponding HTTP status code and error message is returned.

cURL

curl -i localhost:7000/accounts -H "Content-Type: application/json" -H "Authorization: Bearer <Token>" --data '{"username":"freshfox43","password":"secret", "email":"[email protected]","lang":"en"}'

Example Request

1Content-Type: application/json
2Authorization: Bearer z56YzVNyElIp4aic7czvvyhFpnotn6KL
3{
4  "username": "freshfox43",
5  "password": "secret",
6  "email": "[email protected]",
7  "lang": "en"
8}

Example Response

1{
2  "vercode":"y6HUrtrrpQsKRZUzEBalxpIoIKgO2ZJI",
3  "username":"freshfox43"
4}

/accounts/verify

The accounts/verify POST endpoint is used to verify accounts.

Request Body

The request body should be in JSON format and include the following fields:

username: The username of the account to be verified.
vercode: The verification code generated in /accounts request.

Response

Success Response: If the account is successfully verified, a 200 OK response is returned.
Error Response: If there are any validation errors, if the verification code is incorrect, or if the account cannot be verified for any reason, an appropriate error response with the corresponding HTTP status code and error message is returned.

cURL

curl -i localhost:7000/accounts/verify -H "Content-Type: application/json" -H "Authorization: Bearer <Token>" --data '{"username":"freshfox43","vercode":"<verificationCode>"}'

Example Request

1Content-Type: application/json
2Authorization: Bearer z56YzVNyElIp4aic7czvvyhFpnotn6KL
3{
4  "username": "freshfox43",
5  "vercode": "y6HUrtrrpQsKRZUzEBalxpIoIKgO2ZJI"
6}

Restored Features

One of Octet’s main goals is to restore as many features as possible from the game suppport period.

The table with the re-implemented functions is shown below.

Features

Feature	Status	Comments
Character creation/deletion	✔️	No tutorial
Level	⚠️	Same as Quartet
Grade	✔️
Titles	⚠️	Each of them unlocked due to bitwise encoding
Name Tag	✔️	Can be set using /tag
Picket	✔️
Skills	⚠️	Passive skills not working
Visible Range	✔️	Can be changed in octet.cfg
Weapons	✔️
Clothes	✔️
Materials	✔️
Enchant	✔️
Dance	✔️
Potions	✔️
Boxes	❎	Plan to implement soon
Star Item	❎
TAFF	✔️
Monster fight	✔️
NPCs	✔️
Monsters	✔️
Hairdresser	✔️
Capsule Machine	✔️
Lockers	✔️
Warp-gates	✔️
NPC Buy/Sell	✔️
Special Phone	✔️
Chat	✔️
Club	❎
Phone	✔️
Trade	✔️
Auction	❎
Episodes	⚠️	Re-implementation process

Introduction

Overview

Key Features

Target Audience

Documentation Purpose

Getting Started

Windows

Java Installation

Java installation

Adding Java to PATH

MySQL Installation & Configuration

If all the boxes are ticked off, congratulations. MySQL has been configured correctly and is already running on your system.

Linux (Debian-based)

Java Installation

Java installation

MariaDB Installation

MariaDB Installation

MariaDB Configuration

Running Octet

Configuration

IP

db-host

db-username

db-password

db-name

save-interval

whitelist-only

log-global-chat

check-for-updates

developer-mode

enable-api

login-port

api-port

enforce-verified

school-port

comm-port

field-cache

language

world-name

draw-distance-multiplier

base-hp-increment

Score

warpgate

Attributes

episodegate

Attributes

Episode

Attributes

vmachine

Attributes

Product

Attributes

locker

Attributes

hairdresser

Attributes

NPC

Attributes

dialog

Attributes

selection

Attributes

buy

Attributes

beitem

Attributes

coitem

Attributes

enitem

Attributes

sell

Attributes

crystal

Attributes

attachstone

Attributes

detachstone

Attributes

breakstone

Attributes