PHPackages                             bahastriker/pw-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. bahastriker/pw-api

ActiveLibrary[API Development](/categories/api)

bahastriker/pw-api
==================

A package to retrieve data from a Perfect World game server

2.0.1(2mo ago)012MITPHPPHP ^8.1

Since Apr 11Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/BahaStriker/pw-api)[ Packagist](https://packagist.org/packages/bahastriker/pw-api)[ RSS](/packages/bahastriker-pw-api/feed)WikiDiscussions master Synced 2w ago

READMEChangelog (2)DependenciesVersions (4)Used By (0)

Perfect World API
-----------------

[](#perfect-world-api)

Laravel package for retrieving and updating data from a Perfect World game server.

Compatibility
-------------

[](#compatibility)

- PHP: 8.1+
- Laravel: 10.x, 11.x, 12.x

Install
-------

[](#install)

```
composer require bahastriker/pw-api
```

Configuration
-------------

[](#configuration)

Publish the config file:

```
php artisan vendor:publish --tag=pw-api-config
```

Edit `config/pw-api.php`:

```
return [
    'local'          => '127.0.0.1',   // Server IP address
    'server_ip'      => '127.0.0.1',   // Alias for local
    'ports' => [
        'gamedbd'    => 29400,
        'gdeliveryd' => 29100,
        'gacd'       => 29300,
        'client'     => 29000,
    ],
    'game_version'    => '156',         // Protocol version
    'server_version'  => '156',         // Alias for game_version
    'maxbuffer'       => 65536,
    's_block'         => false,
    's_readtype'      => 3,
];
```

### Supported Protocol Versions

[](#supported-protocol-versions)

`07`, `63`, `69`, `70`, `80`, `85`, `88`, `101`, `145`, `156`, `352`

> Version `352` is built from the PW v174 C++ source (build 352) and includes extended storage, glyph, ranking, and admin operations not available in older protocols.

### Settings Resolution

[](#settings-resolution)

This package supports two runtime configuration sources:

- The `setting()` helper (if your app provides it, for example via `akaunting/setting`)
- Fallback to config values from `pw-api.php`

When `setting()` is not available, these config keys are used:

- `pw-api.game_version` (fallback for `server_version`)
- `pw-api.local` (fallback for `server_ip`)

---

Usage
-----

[](#usage)

```
use Striker\PerfectWorldAPI\API;

$api = new API();
```

All methods communicate with the game server over raw TCP sockets. The server must be running and the configured ports must be reachable.

---

API Reference
-------------

[](#api-reference)

### Server Status

[](#server-status)

#### `serverOnline()`

[](#serveronline)

Check if the game server client port is accepting connections.

```
$isOnline = $api->serverOnline(); // true or false
```

#### `ports()`

[](#ports)

Check the status of all configured service ports.

```
$ports = $api->ports();
// [
//     'gamedbd'    => ['port' => 29400, 'open' => true],
//     'gdeliveryd' => ['port' => 29100, 'open' => true],
//     'gacd'       => ['port' => 29300, 'open' => true],
//     'client'     => ['port' => 29000, 'open' => true],
// ]
```

#### `checkRoleOnline($role)`

[](#checkroleonlinerole)

Check if a specific role is currently online. Fetches the full online list and searches for the role ID.

ParameterTypeDescription`$role`intRole ID```
$isOnline = $api->checkRoleOnline(128);
```

#### `getOnlineList()`

[](#getonlinelist)

Get an array of all currently online players.

```
$online = $api->getOnlineList();
// [
//     ['userid' => 32, 'roleid' => 128, 'linkid' => 1, 'localsid' => 5, 'gsid' => 1, 'status' => 0, 'name' => 'PlayerOne'],
//     ...
// ]
```

---

### Account & User Data

[](#account--user-data)

#### `getUser($id)`

[](#getuserid)

Get full account data for a user ID. Returns cash balances, exchange logs, forbid status, login IP, and login time.

ParameterTypeDescription`$id`intUser ID```
$user = $api->getUser(32);
// $user['logicuid']     - Logic UID
// $user['cash']         - Current cash balance
// $user['money']        - In-game money
// $user['status']       - Account status byte
// $user['login_ip']     - Last login IP (parsed)
// $user['login_time']   - Last login timestamp (parsed)
// $user['forbid']       - Array of active bans [{type, time, createtime, reason}]
```

#### `getRoles($user)`

[](#getrolesuser)

Get a list of all characters (roles) belonging to a user account.

ParameterTypeDescription`$user`intUser ID```
$roles = $api->getRoles(32);
// ['count' => 2, 'roles' => [['id' => 128, 'name' => 'MyChar'], ...]]
```

#### `getUserCash($userid)`

[](#getusercashuserid)

Get the cash balance and VIP info for a user account.

ParameterTypeDescription`$userid`intUser ID```
$cash = $api->getUserCash(32);
// ['cash_total' => 10000, 'cash_vip_score_add' => 0, 'cash_vip_level' => 0]
```

---

### Role Data — Read

[](#role-data--read)

#### `getRole($role)`

[](#getrolerole)

Get complete character data in a single call. Returns all sections: `base`, `status`, `pocket`, `equipment`, `storehouse`, and `task`.

ParameterTypeDescription`$role`intRole ID```
$role = $api->getRole(128);
// $role['base']       - Character base info (name, race, class, gender, etc.)
// $role['status']     - Level, exp, HP/MP, position, reputation, skills, etc.
// $role['pocket']     - Inventory items
// $role['equipment']  - Equipped items
// $role['storehouse'] - Bank/storehouse items
// $role['task']       - Quest data and task inventory
```

#### `getRoleBase($role)`

[](#getrolebaserole)

Get only the base section of a character (name, race, class, creation time, marriage, bans).

ParameterTypeDescription`$role`intRole ID```
$base = $api->getRoleBase(128);
// $base['name']           - Character name
// $base['race']           - Race ID
// $base['cls']            - Class ID
// $base['gender']         - Gender (0 = male, 1 = female)
// $base['status']         - 0 = active, 1 = deleted
// $base['delete_time']    - Deletion timestamp (0 if active)
// $base['create_time']    - Creation timestamp
// $base['lastlogin_time'] - Last login timestamp
// $base['spouse']         - Spouse role ID (0 if unmarried)
// $base['userid']         - Owning user ID
// $base['custom_data']    - Character appearance data (hex octets)
// $base['forbid']         - Array of role-level bans
```

#### `getRoleStatus($role)`

[](#getrolestatusrole)

Get character status: level, experience, position, stats, skill data, and various octet fields.

ParameterTypeDescription`$role`intRole ID```
$status = $api->getRoleStatus(128);
// $status['level']            - Current level
// $status['level2']           - Reincarnation level
// $status['exp']              - Experience points
// $status['sp']               - Spirit points
// $status['hp'], ['mp']       - Current HP/MP
// $status['posx/y/z']         - World position (float)
// $status['worldtag']         - Current world/map ID
// $status['reputation']       - Reputation value
// $status['invader_state']    - PK mode state
// $status['skills']           - Skill data (hex octets)
// $status['property']         - Extended properties (hex octets)
// $status['var_data']         - PK/PvP variables (hex octets)
// $status['force_data']       - Force/faction reputation (hex octets)
// $status['meridian_data']    - Meridian data (hex octets)
// $status['reincarnation_data'] - Reincarnation data (hex octets)
```

#### `getRoleInventory($role)`

[](#getroleinventoryrole)

Get inventory (pocket) contents.

ParameterTypeDescription`$role`intRole ID```
$inv = $api->getRoleInventory(128);
// $inv['icapacity']    - Inventory capacity
// $inv['money']        - Coin in inventory
// $inv['inv']          - Array of items [{id, pos, count, max_count, data, proctype, expire_date, guid1, guid2, mask}]
// $inv['silver_money'] - Silver coin (v174+)
```

#### `getRoleEquipment($role)`

[](#getroleequipmentrole)

Get currently equipped items.

ParameterTypeDescription`$role`intRole ID```
$eqp = $api->getRoleEquipment(128);
// $eqp['eqp'] - Array of equipped items [{id, pos, count, max_count, data, ...}]
```

#### `getRoleStorehouse($role)`

[](#getrolestorehouserole)

Get bank/storehouse contents including dress and material tabs.

ParameterTypeDescription`$role`intRole ID```
$store = $api->getRoleStorehouse(128);
// $store['capacity'] - Storage capacity
// $store['money']    - Stored coins
// $store['store']    - Main storage items
// $store['dress']    - Fashion tab items
// $store['material'] - Material tab items
// $store['generalcard'] - General card tab items
```

#### `getRoleTask($role)`

[](#getroletaskrole)

Get quest/task data and task inventory items.

ParameterTypeDescription`$role`intRole ID```
$task = $api->getRoleTask(128);
// $task['task_data']      - Active task data (hex octets)
// $task['task_complete']  - Completed tasks (hex octets)
// $task['task_finishtime'] - Task finish times (hex octets)
// $task['task_inventory'] - Task inventory items
```

#### `getRolePetBadge($role)`

[](#getrolepetbadgerole)

Get pet badge inventory.

ParameterTypeDescription`$role`intRole ID```
$badges = $api->getRolePetBadge(128);
```

#### `getRoleFriends($role)`

[](#getrolefriendsrole)

Get friend list and friend groups for a character.

ParameterTypeDescription`$role`intRole ID```
$friends = $api->getRoleFriends(128);
// $friends['groupinfo']  - Friend groups [{gid, name}]
// $friends['friendinfo'] - Friends [{rid, cls, gid, name}]
```

---

### Role Data — Write

[](#role-data--write)

#### `putRole($role, $params)`

[](#putrolerole-params)

Save complete character data. The `$params` array must contain the same section structure as returned by `getRole()`.

ParameterTypeDescription`$role`intRole ID`$params`arrayFull role data with sections: `base`, `status`, `pocket`, `equipment`, `storehouse`, `task````
$role = $api->getRole(128);
$role['status']['level'] = 150;
$role['status']['hp'] = 50000;
$api->putRole(128, $role);
```

> Items arrays are auto-wrapped: if you pass a single item (flat array with `id` key) instead of an array of items, it will be normalized.

---

### Octet Parsing

[](#octet-parsing)

#### `parseOctet($octet, $name)`

[](#parseoctetoctet-name)

Parse a hex-encoded octet string into a structured array using a named octet definition from the protocol file.

ParameterTypeDescription`$octet`stringHex-encoded octet data`$name`stringOctet type name: `var_data`, `property`, `force_data`, `faction_contrib`, `title_data````
$status = $api->getRoleStatus(128);

// Parse PK/PvP data
$varData = $api->parseOctet($status['var_data'], 'var_data');
// $varData['pk_count']         - PK kill count
// $varData['pvp_flag']         - PvP flag
// $varData['dead_flag']        - Death flag
// $varData['trashbox_size']    - Trash box size

// Parse combat properties
$props = $api->parseOctet($status['property'], 'property');
// $props['hp'], ['mp']         - Max HP/MP
// $props['attack']             - Physical attack
// $props['defense']            - Physical defense
// $props['damage_low/high']    - Damage range
// $props['resistance']         - Elemental resistances [1-5]

// Parse force reputation
$force = $api->parseOctet($status['force_data'], 'force_data');
// $force['cur_force_id']  - Active force ID
// $force['force']         - Array of [{force_id, reputation, contribution}]

// Parse faction contribution
$contrib = $api->parseOctet($status['faction_contrib'], 'faction_contrib');
// $contrib['consume_contrib']   - Consumed contribution
// $contrib['exp_contrib']       - Experience contribution
// $contrib['cumulate_contrib']  - Total accumulated contribution
```

#### `getRolePvp($var_data)`

[](#getrolepvpvar_data)

Convenience method to extract PK count and death flag from a `var_data` hex octet string.

ParameterTypeDescription`$var_data`stringHex-encoded var\_data octet (from `getRoleStatus()['var_data']`)```
$status = $api->getRoleStatus(128);
$pvp = $api->getRolePvp($status['var_data']);
// ['pk_count' => 5, 'dead_flag' => 0]
```

---

### ID Lookups

[](#id-lookups)

#### `getRoleid($rolename)`

[](#getroleidrolename)

Look up a role ID by character name.

ParameterTypeDescription`$rolename`stringCharacter name```
$id = $api->getRoleid('PlayerOne'); // 128
```

#### `roleIdToUserId($roleid)` v174+

[](#roleidtouseridroleid-v174)

Convert a role ID to its owning user (account) ID.

ParameterTypeDescription`$roleid`intRole ID```
$userId = $api->roleIdToUserId(128); // 32
```

#### `userIdToLogicUid($userid)` v174+

[](#useridtologicuiduserid-v174)

Convert a user ID to its logic UID.

ParameterTypeDescription`$userid`intUser ID```
$logicUid = $api->userIdToLogicUid(32);
```

---

### Character Management

[](#character-management)

#### `renameRole($role, $oldname, $newname)`

[](#renamerolerole-oldname-newname)

Rename a character. The old name must match the current name.

ParameterTypeDescription`$role`intRole ID`$oldname`stringCurrent character name`$newname`stringNew character name```
$api->renameRole(128, 'OldName', 'NewName');
```

#### `undoDeleteRole($role)` v174+

[](#undodeleterolerole-v174)

Restore a deleted character.

ParameterTypeDescription`$role`intRole ID```
$api->undoDeleteRole(128);
```

#### `copyRole($srcroleid, $dstroleid)` v174+

[](#copyrolesrcroleid-dstroleid-v174)

Copy all data from one character to another. The destination role must already exist.

ParameterTypeDescription`$srcroleid`intSource role ID`$dstroleid`intDestination role ID```
$api->copyRole(128, 256);
```

#### `positionReset($role, $worldtag, $x, $y, $z)` v174+

[](#positionresetrole-worldtag-x-y-z-v174)

Teleport an offline character to a specific position. The character must be logged out.

ParameterTypeDescription`$role`intRole ID`$worldtag`intWorld/map tag (e.g., `1` for main world)`$x`floatX coordinate`$y`floatY coordinate`$z`floatZ coordinate```
$api->positionReset(128, 1, 4200.0, 700.0, 3800.0);
```

#### `modifyRoleData($role, $mask, $params)` v174+

[](#modifyroledatarole-mask-params-v174)

Directly modify character attributes. Only fields enabled by the bitmask are applied.

ParameterTypeDescription`$role`intRole ID`$mask`intBitmask of fields to modify`$params`arrayValues for enabled fields**Mask bits:**

BitFieldKey0x01Level`level`0x02Experience`exp`0x04Inventory money`pocket_money`0x08Storehouse money`store_money`0x10PK value`pkvalue`0x20Reputation`reputation`0x40Potential (spirit)`potential`0x80Occupation (class)`occupation````
// Set level to 105 and reset PK value to 0
$api->modifyRoleData(128, 0x01 | 0x10, [
    'level' => 105,
    'pkvalue' => 0,
]);

// Set experience to a large value (int64)
$api->modifyRoleData(128, 0x02, [
    'exp' => 2000000000,
]);
```

#### `clearStorehousePasswd($role, $rolename)` v174+

[](#clearstorehousepasswdrole-rolename-v174)

Clear the storehouse and cash password for a character.

ParameterTypeDescription`$role`intRole ID`$rolename`stringCharacter name```
$api->clearStorehousePasswd(128, 'PlayerOne');
```

---

### Faction Operations

[](#faction-operations)

#### `getUserFaction($id)`

[](#getuserfactionid)

Get a character's faction membership info.

ParameterTypeDescription`$id`intRole ID```
$faction = $api->getUserFaction(128);
// $faction['rid']       - Role ID
// $faction['name']      - Character name
// $faction['fid']       - Faction ID (0 if none)
// $faction['cls']       - Class
// $faction['role']      - Faction role (0=member, 1=officer, etc.)
// $faction['nickname']  - Faction nickname
```

#### `getFactionInfo($id)`

[](#getfactioninfoid)

Get basic faction info including the member list (role IDs and roles only).

ParameterTypeDescription`$id`intFaction ID```
$info = $api->getFactionInfo(1);
// $info['fid']      - Faction ID
// $info['name']     - Faction name
// $info['level']    - Faction level
// $info['master']   - Leader: ['roleid' => ..., 'role' => ...]
// $info['member']   - Members: [['roleid' => ..., 'role' => ...], ...]
// $info['announce'] - Announcement text
// $info['sysinfo']  - System info (hex octets)
```

#### `getFactionDetail($id)`

[](#getfactiondetailid)

Get detailed faction info with full member data, alliances, and hostiles.

ParameterTypeDescription`$id`intFaction ID```
$detail = $api->getFactionDetail(1);
// $detail['fid']          - Faction ID
// $detail['name']         - Faction name
// $detail['level']        - Faction level
// $detail['master']       - Leader role ID (int)
// $detail['announce']     - Announcement text
// $detail['member']       - Full member info:
//     [['roleid', 'level', 'occupation', 'froleid', 'login_day', 'online_status',
//       'name', 'nickname', 'contrib_old', 'delayexpel', 'expeltime',
//       'reputation', 'reincarn_times', 'gender', 'contrib', 'guild_money'], ...]
// $detail['alliance']     - Allied factions [{fid, end_time}]
// $detail['hostile']      - Hostile factions [{fid, end_time}]
// $detail['apply']        - Pending relation applications [{type, fid, end_time}]
// $detail['last_op_time'] - Last operation timestamp
// $detail['unifid']       - Unified faction ID (int64)
```

#### `addFaction($roleid, $name, $fid)`

[](#addfactionroleid-name-fid)

Create a new faction.

ParameterTypeDescription`$roleid`intLeader role ID`$name`stringFaction name`$fid`intFaction ID to assign```
$api->addFaction(128, 'MyGuild', 1);
```

#### `delFaction($fid)`

[](#delfactionfid)

Delete a faction.

ParameterTypeDescription`$fid`intFaction ID```
$api->delFaction(1);
```

#### `upgradeFaction($roleid, $fid, $level)`

[](#upgradefactionroleid-fid-level)

Set a faction's level.

ParameterTypeDescription`$roleid`intRole ID performing the upgrade`$fid`intFaction ID`$level`intNew level```
$api->upgradeFaction(128, 1, 3);
```

---

### Territory War

[](#territory-war)

#### `getTerritories()`

[](#getterritories)

Get the full list of territory war zones with ownership, timing, and challenge data.

```
$territories = $api->getTerritories();
// $territories['Territory'] - Array of territories:
//     [['id', 'level', 'owner', 'occupy_time', 'challenger', 'deposit',
//       'cutoff_time', 'battle_time', 'bonus_time', 'color', 'status',
//       'timeout', 'challenge_time', 'challengerdetails',
//       'reserved1', 'reserved2', 'reserved3'], ...]
```

---

### Mail

[](#mail)

#### `sendMail($receiver, $title, $context, $item, $money)`

[](#sendmailreceiver-title-context-item-money)

Send an in-game mail to a character. Optionally attach one item and/or money.

ParameterTypeDescription`$receiver`intRecipient role ID`$title`stringMail subject`$context`stringMail body text`$item`arrayItem attachment (optional, default: empty)`$money`intCoin attachment (optional, default: `0`)```
// Text-only mail
$api->sendMail(128, 'Welcome', 'Welcome to the server!');

// Mail with item attachment
$api->sendMail(128, 'Gift', 'Here is your item.', [
    'id'          => 21652,   // Item template ID
    'pos'         => 0,
    'count'       => 1,
    'max_count'   => 1,
    'data'        => '',      // Item octet data (hex)
    'proctype'    => 0,
    'expire_date' => 0,
    'guid1'       => 0,
    'guid2'       => 0,
    'mask'        => 0,
], 1000000);
```

#### `getMailList($role)` v174+

[](#getmaillistrole-v174)

Get a list of mail headers for a character.

ParameterTypeDescription`$role`intRole ID```
$mails = $api->getMailList(128);
// [
//     ['id' => 0, 'sender' => 256, 'sndr_type' => 0, 'receiver' => 128,
//      'title' => 'Hello', 'send_time' => 1700000000, 'attribute' => 0, 'sender_name' => 'Admin'],
//     ...
// ]
```

#### `deleteMail($role, $mailid)` v174+

[](#deletemailrole-mailid-v174)

Delete a specific mail by its ID.

ParameterTypeDescription`$role`intRole ID`$mailid`intMail ID (from `getMailList()`)```
$api->deleteMail(128, 0);
```

---

### Chat & Announcements

[](#chat--announcements)

#### `WorldChat($role, $msg, $channel)`

[](#worldchatrole-msg-channel)

Send a message to the game chat on a specific channel.

ParameterTypeDescription`$role`intSender role ID`$msg`stringMessage text`$channel`intChannel number (0 = normal, 1 = world, 7 = trade, 9 = system, etc.)```
$api->WorldChat(128, 'Server restarting in 5 minutes!', 9);
```

#### `announce($role, $msg)` v174+

[](#announcerole-msg-v174)

Send a GM announcement broadcast to the entire server. Uses the system channel.

ParameterTypeDescription`$role`intGM role ID`$msg`stringAnnouncement text```
$api->announce(128, 'Maintenance in 30 minutes.');
```

---

### Bans & Mutes

[](#bans--mutes)

#### `forbidAcc($role, $time, $reason)`

[](#forbidaccrole-time-reason)

Ban an account. All characters on the account will be unable to log in.

ParameterTypeDescription`$role`intUser ID`$time`intBan duration in seconds (`-1` for permanent)`$reason`stringBan reason```
$api->forbidAcc(32, 86400, 'Violation of rules');   // 24-hour ban
$api->forbidAcc(32, -1, 'Permanent ban');            // Permanent
$api->forbidAcc(32, 0, '');                          // Unban
```

#### `forbidRole($role, $time, $reason)`

[](#forbidrolerole-time-reason)

Ban a specific character.

ParameterTypeDescription`$role`intRole ID`$time`intBan duration in seconds`$reason`stringBan reason```
$api->forbidRole(128, 3600, 'Temporary suspension');
```

#### `muteAcc($role, $time, $reason)`

[](#muteaccrole-time-reason)

Mute an account (prevent all characters from chatting).

ParameterTypeDescription`$role`intUser ID`$time`intMute duration in seconds`$reason`stringMute reason```
$api->muteAcc(32, 600, 'Spam');
```

#### `muteRole($role, $time, $reason)`

[](#muterolerole-time-reason)

Mute a specific character.

ParameterTypeDescription`$role`intRole ID`$time`intMute duration in seconds`$reason`stringMute reason```
$api->muteRole(128, 600, 'Spam');
```

---

### Extended Role Data v174+

[](#extended-role-data-v174)

These methods require protocol version `352` or later.

#### `getNewRoleDetail($role)`

[](#getnewroledetailrole)

Get extended character data including PvP statistics, kill/death counts, silver money, and various octets for glyph, codex, celestial systems, etc.

ParameterTypeDescription`$role`intRole ID```
$detail = $api->getNewRoleDetail(128);
// $detail['roleid']                  - Role ID
// $detail['pk_time']                 - Last PK timestamp
// $detail['pk_status']               - PK status
// $detail['money_silver']            - Silver coin balance
// $detail['pvp_rank']                - PvP rank
// $detail['pvp_rank_exp']            - PvP rank experience
// $detail['player_kill']             - Total player kills
// $detail['monster_kill']            - Total monster kills
// $detail['player_death']            - Total player deaths
// $detail['monster_death']           - Total monster deaths
// $detail['has_astrolabe_lock']      - Astrolabe lock flag
// $detail['enabled_fashion_weapon']  - Fashion weapon toggle
// $detail['double_factor_exp/sp/realm'] - Double rate flags
// $detail['glyph']                   - Glyph data (hex octets)
// $detail['codex']                   - Codex data (hex octets)
// $detail['celestial']               - Celestial data (hex octets)
// $detail['pet_skin']                - Pet skin data (hex octets)
// ... (see protocol file for full field list)
```

#### `setNewRoleDetail($role, $params)`

[](#setnewroledetailrole-params)

Save extended character data. Pass the full array (e.g., from `getNewRoleDetail()` with modifications).

ParameterTypeDescription`$role`intRole ID`$params`arrayFull new role detail data```
$detail = $api->getNewRoleDetail(128);
$detail['money_silver'] = 50000;
$detail['pvp_rank'] = 5;
$api->setNewRoleDetail(128, $detail);
```

---

### Extended Storage v174+

[](#extended-storage-v174)

#### `getNewTrashBox($role)`

[](#getnewtrashboxrole)

Get extra storage box tabs (boxes 4-7) for a character.

ParameterTypeDescription`$role`intRole ID```
$trash = $api->getNewTrashBox(128);
// $trash['roleid']  - Role ID
// $trash['size4']   - Box 4 capacity
// $trash['box4']    - Box 4 items [{id, pos, count, max_count, data, ...}]
// $trash['size5']   - Box 5 capacity
// $trash['box5']    - Box 5 items
// $trash['size6']   - Box 6 capacity
// $trash['box6']    - Box 6 items
// $trash['size7']   - Box 7 capacity
// $trash['box7']    - Box 7 items
```

#### `setNewTrashBox($role, $params)`

[](#setnewtrashboxrole-params)

Save extra storage box data.

ParameterTypeDescription`$role`intRole ID`$params`arrayTrash box data```
$trash = $api->getNewTrashBox(128);
$trash['size4'] = 16;
$api->setNewTrashBox(128, $trash);
```

#### `getGlyphBox($role)`

[](#getglyphboxrole)

Get glyph box inventory.

ParameterTypeDescription`$role`intRole ID```
$glyph = $api->getGlyphBox(128);
// $glyph['roleid']    - Role ID
// $glyph['size']      - Glyph box capacity
// $glyph['glyph_box'] - Glyph items [{id, pos, count, max_count, data, ...}]
```

#### `setGlyphBox($role, $params)`

[](#setglyphboxrole-params)

Save glyph box inventory.

ParameterTypeDescription`$role`intRole ID`$params`arrayGlyph box data```
$glyph = $api->getGlyphBox(128);
$glyph['size'] = 32;
$api->setGlyphBox(128, $glyph);
```

#### `getRoleStorage($role, $type)`

[](#getrolestoragerole-type)

Get a specific storage type by name. This is a unified interface for multiple storage systems.

ParameterTypeDescription`$role`intRole ID`$type`stringStorage type name**Available types:**

TypeDescriptionFields`lotteryItems`Lottery item entries`roleid`, `treasure_items` (octets)`lotteryData`Lottery progress`roleid`, `level`, `score`, `lottery_data` (octets)`treasureData`Treasure box data`roleid`, `score`, `treasure_data` (octets)`libItems`Library items`roleid`, `lib_items` (octets)`glyphData`Glyph system data`roleid`, `glyph_data` (octets)`celestialData`Celestial system data`roleid`, `celestial` (octets)`repositoryData`Repository data`roleid`, `repository_data` (octets)`activityData`Activity/event data`roleid`, `activity` (octets)`petSkin`Pet skin data`roleid`, `pet_skin` (octets)```
$lottery = $api->getRoleStorage(128, 'lotteryData');
// ['roleid' => 128, 'level' => 3, 'score' => 1500, 'lottery_data' => '...']

$celestial = $api->getRoleStorage(128, 'celestialData');
// ['roleid' => 128, 'celestial' => '...']
```

#### `setRoleStorage($role, $type, $params)`

[](#setrolestoragerole-type-params)

Save a specific storage type by name.

ParameterTypeDescription`$role`intRole ID`$type`stringStorage type name (same as `getRoleStorage`)`$params`arrayStorage data```
$lottery = $api->getRoleStorage(128, 'lotteryData');
$lottery['score'] = 5000;
$api->setRoleStorage(128, 'lotteryData', $lottery);
```

---

### Lua Storage v174+

[](#lua-storage-v174)

#### `getLuaStorage($key, $data_mask)`

[](#getluastoragekey-data_mask)

Read a Lua storage entry by key. Used for server-side Lua script data.

ParameterTypeDefaultDescription`$key`int—Storage key`$data_mask`int`1`Data mask```
$data = $api->getLuaStorage(100);
// ['key' => 100, 'data' => '...']  (hex octets)
```

#### `setLuaStorage($key, $value, $data_mask)`

[](#setluastoragekey-value-data_mask)

Write a Lua storage entry.

ParameterTypeDefaultDescription`$key`int—Storage key`$value`string—Hex-encoded octet data`$data_mask`int`1`Data mask```
$api->setLuaStorage(100, 'deadbeef');
```

---

### Player Ranking v174+

[](#player-ranking-v174)

#### `getPlayerRanking($role)`

[](#getplayerrankingrole)

Get ranking data for a character.

ParameterTypeDescription`$role`intRole ID```
$rank = $api->getPlayerRanking(128);
// $rank['role_id']         - Role ID
// $rank['user_id']         - User ID
// $rank['cls']             - Class
// $rank['score_pve']       - PvE score
// $rank['score_pvp']       - PvP score
// $rank['kill_monsters']   - Total monster kills
// $rank['die_monsters']    - Total monster deaths
// $rank['kill_players']    - Total player kills
// $rank['die_players']     - Total player deaths
// $rank['score_pve_level'] - PvE level score
// $rank['score_pvp_level'] - PvP level score
// $rank['fama_score']      - Fame score
// $rank['level']           - Current level
// $rank['level2']          - Reincarnation level
// $rank['name']            - Character name
```

---

### Server Data & Global Control v174+

[](#server-data--global-control-v174)

#### `getServerData($world_tag, $data_mask)`

[](#getserverdataworld_tag-data_mask)

Get server-wide data (wedding, DPS rankings, etc.).

ParameterTypeDefaultDescription`$world_tag`int`0`World/map tag`$data_mask`int`1`Data mask```
$data = $api->getServerData();
// $data['world_tag']     - World tag
// $data['wedding_data']  - Wedding system data (hex octets)
// $data['dpsrank_data']  - DPS ranking data (hex octets)
```

#### `loadGlobalControl()`

[](#loadglobalcontrol)

Load the current global control settings (cash exchange, feature toggles, forbidden items/skills/tasks).

```
$ctrl = $api->loadGlobalControl();
// $ctrl['cash_money_exchange_open'] - Gold exchange enabled (0/1)
// $ctrl['cash_money_exchange_rate'] - Exchange rate
// $ctrl['forbid_ctrl_list']         - Disabled control IDs [{item => id}]
// $ctrl['forbid_item_list']         - Forbidden item IDs
// $ctrl['forbid_service_list']      - Forbidden service IDs
// $ctrl['forbid_task_list']         - Forbidden task IDs
// $ctrl['forbid_skill_list']        - Forbidden skill IDs
// $ctrl['trigger_ctrl_list']        - Trigger control IDs
// $ctrl['forbid_shopitem_list']     - Forbidden shop item IDs
// $ctrl['forbid_recipe_list']       - Forbidden recipe IDs
```

#### `putGlobalControl($params)`

[](#putglobalcontrolparams)

Save global control settings. Pass the full structure (e.g., from `loadGlobalControl()` with modifications).

ParameterTypeDescription`$params`arrayGlobal control data```
$ctrl = $api->loadGlobalControl();
$ctrl['cash_money_exchange_open'] = 1;
$ctrl['cash_money_exchange_rate'] = 200;
$api->putGlobalControl($ctrl);
```

---

### Raw Database Access

[](#raw-database-access)

#### `getRaw($table, $handler, $key)`

[](#getrawtable-handler-key)

Perform a raw database table read from gamedbd.

ParameterTypeDefaultDescription`$table`string—Table name`$handler`string`''`Handler (hex octets)`$key`string`''`Key (hex octets)```
$raw = $api->getRaw('base');
// $raw['handle'] - Handle data (hex octets)
// $raw['Raw']    - Array of key-value pairs [['key' => '...', 'value' => '...'], ...]
```

---

### Skill Generation

[](#skill-generation)

#### `generateSkill($params)`

[](#generateskillparams)

Append a skill to existing skill octet data. Returns the modified skill hex string.

ParameterTypeDescription`$params`arrayKeys: `skills` (existing skill hex), `id` (skill ID), `level`, `progress````
$status = $api->getRoleStatus(128);
$newSkills = $api->generateSkill([
    'skills'   => $status['skills'],
    'id'       => 100,
    'level'    => 10,
    'progress' => 0,
]);
```

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance84

Actively maintained with recent releases

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity45

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

80d ago

Major Versions

1.7.4 → 2.0.02026-04-11

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/9751325?v=4)[Baha Striker](/maintainers/BahaStriker)[@BahaStriker](https://github.com/BahaStriker)

---

Top Contributors

[![BahaStriker](https://avatars.githubusercontent.com/u/9751325?v=4)](https://github.com/BahaStriker "BahaStriker (13 commits)")

### Embed Badge

![Health badge](/badges/bahastriker-pw-api/health.svg)

```
[![Health](https://phpackages.com/badges/bahastriker-pw-api/health.svg)](https://phpackages.com/packages/bahastriker-pw-api)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35816.3M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24015.5M18](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172437.8k11](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

94452.6k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)