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:

  1. Open System Properties: Right-click on “This PC” or “My Computer” and select “Properties”. Then, click on “Advanced system settings” on the left sidebar.

  2. Open Environment Variables: In the System Properties window, click on the “Environment Variables” button.

  3. 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.

  4. 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.

  5. 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.

  6. 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

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

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

login-port

Port number of game’s Login port. It can be modified in Octet but game clients usually use port 10000 as it’s hardcoded.

Example: login-port=10000

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

    Tag

    💬 Chat only

    Sets issuer’s tag color.

    Syntax

    tag <value>

    • [value]: Value from 0-7.

    Permission code: command.tag

    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:

    1. 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.

    2. 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.
    3. 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.
    1. 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