SphereServer

https://github.com/sphereserver/source-archive
Admin
SphereServer is a free, open-source server emulator for the MMORPG Ultima Online that allows players...
Tokens:147,498
Snippets:1,152
Trust Score:6.2
License:Apache-2.0
Update:10 months ago
Show doc for...
Tokens:
Raw
### Implementing Test Fixtures with setUp() and tearDown() in CxxTest

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

Illustrates how to use the setUp() and tearDown() virtual functions in a CxxTest::TestSuite to manage test fixtures. The setUp() method is executed before each test case, and tearDown() is executed after each test case, allowing for common setup and cleanup operations like creating and removing directories.

```cpp
class TestFileOps : public CxxTest::TestSuite {
public:
   void setUp() { mkdir( "playground" ); }
   void tearDown() { system( "rm -Rf playground"); }

   void testCreateFile()
   {
      FileCreator fc( "playground" );
      fc.createFile( "test.bin" );
      TS_ASSERT_EQUALS( access( "playground/test.bin", 0 ), 0 );
   }
};

```

--------------------------------

### Integrate CxxTest with Visual Studio

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This integration uses a three-project setup in Visual Studio: one for generating test files with cxxtestgen, one for compiling the generated code, and one for running the tests. Test results are displayed as compilation errors and warnings. Configuration may require tweaking makefiles and project options, with a provided script to automate some steps.

```batch
sample/msvc/FixFiles.bat
```

--------------------------------

### Integrate CxxTest with Windows DDK

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This method allows unit testing for device drivers using the 'build' utility. The generated test file is added as an extra dependency in the 'Makefile.inc' file using the 'NTBUILDTARGET0' macro. An example configuration is available in the 'sample/winddk' directory of the CxxTest distribution.

```makefile
Makefile.inc
```

--------------------------------

### Implement Global Fixtures for CXXTest

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This C++ code illustrates the concept of global fixtures in CXXTest, which allow setup and teardown code to be executed once before and after all test cases across all test suites. Global fixtures inherit from CxxTest::GlobalFixture and their static objects ensure timely execution.

```cpp
// Example of a global fixture class structure
class MyGlobalFixture : public CxxTest::GlobalFixture {
public:
    bool setUpWorld() {
        // Code to execute once at the start of testing
        return true; // Indicate success
    }

    void tearDownWorld() {
        // Code to execute once at the end of testing
    }

    bool setUp() {
        // Code to execute before each test case
        return true; // Indicate success
    }

    void tearDown() {
        // Code to execute after each test case
    }
};

// Instantiate a static object to ensure execution
// static MyGlobalFixture globalFixture;

```

--------------------------------

### Generate CxxTest GUI with QtGui (Qt)

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This command generates CxxTest runner files with a Qt GUI interface, provided the Qt framework is installed. It requires Perl and the cxxtestgen.pl script. Compilation necessitates linking against Qt headers and libraries.

```bash
cxxtestgen.pl --gui=QtGui
```

--------------------------------

### Updated Item Creation and Resource Handling in Scripts

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

This example shows the refactoring of item creation logic, moving resource requirements from skill menus to item definitions and using DEFNAME constants for item identification. This improves clarity and maintainability in the scripting process.

```SphereScript
ONOPTION=GOLDEN_CHAINMAIL_COIF Golden Chainmail Coif (10 ingots)
MAKEITEM=GOLDEN_CHAINMAIL_COIF
```

--------------------------------

### TUS Server Startup Success Message

Source: https://github.com/sphereserver/source-archive/blob/main/0.55.403/graysvr/readme.txt

The console message indicating a successful TUS server startup. This confirms that all necessary items have been accounted for and the server is ready for client connections.

```text
All Items Accounted for, Startup Complete
```

--------------------------------

### Ultima Online Client Login Configuration

Source: https://github.com/sphereserver/source-archive/blob/main/0.55.403/graysvr/readme.txt

Modification of the UO client's login.cfg file to direct the client to the TUS server. This involves commenting out existing login server entries and adding the TUS server's IP and port.

```cfg
;Loginservers for Ultima Online
;Do not edit this file or patching will fail! Always save a backup.
;LoginServer=login.owo.com,7775
;LoginServer=login.owo.com,7775
;LoginServer=login.owo.com,7776
;LoginServer=login.owo.com,7776
LoginServer=127.0.0.1,2593
```

--------------------------------

### Dart Trap Configurations

Source: https://github.com/sphereserver/source-archive/blob/main/GrayWorld 10/graysvr/items.txt

Details various configurations for 'dart trap' entries. This section outlines the parameters for each distinct dart trap setup.

```text
112c: 00,F00,00,01,Wff,L03,?00000000,A00000000,?0000,H00,'dart trap'
112d: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'dart trap'
112e: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'dart trap'
1130: 00,F00,00,01,Wff,L03,?00000000,A00000000,?0000,H00,'dart trap'
1131: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'dart trap'
1132: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'dart trap'
```

--------------------------------

### Axe Trap Configurations

Source: https://github.com/sphereserver/source-archive/blob/main/GrayWorld 10/graysvr/items.txt

Lists different configurations for 'axe trap' entries. Each line specifies the parameters for a unique axe trap setup.

```text
1133: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1134: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1135: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1136: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1137: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1138: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1139: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1140: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1141: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1142: 00,F00,00,04,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
1143: 00,F00,00,05,Wff,L02,?00000000,A00000000,?0000,H00,'axe trap'
1144: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
114b: 00,F00,00,00,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
114c: 00,F00,00,01,Wff,L04,?00000000,A00000000,?0000,H00,'axe trap'
114d: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
114e: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
114f: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'axe trap'
```

--------------------------------

### Implement World Fixtures for CXXTest

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This C++ code demonstrates the implementation of 'World Fixtures' in CXXTest, which are specifically designed for code executed once at the very beginning and end of the entire testing process. It involves creating global fixture objects that implement setUpWorld() and tearDownWorld() methods.

```cpp
// Example of a world fixture class structure
class MyWorldFixture : public CxxTest::GlobalFixture {
public:
    bool setUpWorld() {
        // Code to execute once at the start of the testing process
        return true; // Indicate success
    }

    void tearDownWorld() {
        // Code to execute once at the end of the testing process
    }
};

// Instantiate a static object to ensure execution
// static MyWorldFixture worldFixture;

```

--------------------------------

### Example of Localized Message with Arguments (0xCC)

Source: https://github.com/sphereserver/source-archive/blob/main/coding_docs/packets/detailed_packets.htm

Illustrates how the 0xCC packet's arguments field is used with localized messages. A message like '~1_COUNT~ items, ~2_WEIGHT~ stones' can be populated with data such as '5\t10', where '\t' separates the arguments for 'COUNT' and 'WEIGHT'.

```csharp
int localizationNumber = 1050044;
string text = "5\t10"; // Represents 5 items and 10 stones
```

--------------------------------

### Fire Trap Configurations

Source: https://github.com/sphereserver/source-archive/blob/main/GrayWorld 10/graysvr/items.txt

Lists various configurations for 'fire trap' entries. Each line represents a distinct trap setup with its own set of parameters.

```text
1111: 00,F40,80,01,Wff,L36,?00000000,A00000000,?0000,H00,'fire trap'
1112: 00,F40,80,01,Wff,L36,?00000000,A00000000,?0000,H00,'fire trap'
1113: 00,F40,80,01,Wff,L36,?00000000,A00000000,?0000,H00,'fire trap'
1114: 00,F40,80,01,Wff,L36,?00000000,A00000000,?0000,H00,'fire trap'
1115: 00,F40,80,01,Wff,L36,?00000000,A00000000,?0000,H00,'fire trap'
```

--------------------------------

### Implement Real Global Function for Production Build (C++)

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

For the production build, define CXXTEST_MOCK_REAL_SOURCE_FILE before including the mock header. This links the T:: function calls to the original, real global function implementation.

```cpp
// real_time.cpp
#define CXXTEST_MOCK_REAL_SOURCE_FILE
#include <T/time.h>

```

--------------------------------

### Prepare Global Function for Mocking with CXXTEST_MOCK_GLOBAL (C++)

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This macro prepares a global function for mocking. It defines the return type, function name, prototype, and argument list. This allows the function to be called via the T namespace in tested code and overridden in tests.

```cpp
#include <time.h>
#include <cxxtest/Mock.h>

CXXTEST_MOCK_GLOBAL( time_t,        /* Return type          */
                   time,          /* Name of the function */
                   ( time_t *t ), /* Prototype            */
                   ( t )          /* Argument list        */ );

```

--------------------------------

### Client Event Processing and Custom Commands in C++

Source: https://context7.com/sphereserver/source-archive/llms.txt

Handles client input events like movement and commands using a verb system. Includes examples for skill menu selection and custom verbs such as SUMMON and TRANSPORT. This code is crucial for client-server interaction and command execution.

```cpp
// Client commands are processed through verb system
bool CClient::Cmd_Skill_Menu(CResourceID rid, int selection) {
    // Handle skill menu selection
    CResourceDef* pResDef = g_Cfg.ResourceGetDef(rid);
    if (!pResDef)
        return false;

    CSkillMenuDef* pSkillMenu = dynamic_cast<CSkillMenuDef*>(pResDef);
    if (!pSkillMenu)
        return false;

    // Process selection
    return m_pChar->Skill_Start(pSkillMenu->GetSkill(selection));
}

// Custom client verbs (commands)
bool CChar::r_Verb(CScript& s, CTextConsole* pSrc) {
    // Example custom command handling
    LPCTSTR pszKey = s.GetKey();

    if (!strcmpi(pszKey, "SUMMON")) {
        // .summon c_orc
        CREID_TYPE id = static_cast<CREID_TYPE>(
            g_Cfg.ResourceGetIndexType(RES_CHARDEF, s.GetArgStr())
        );
        CChar* pNPC = CChar::CreateBasic(id);
        if (pNPC) {
            pNPC->MoveToChar(GetTopPoint());
            pNPC->NPC_CreateTrigger();
            pNPC->Update();
            SysMessagef("Summoned %s", pNPC->GetName());
        }
        return true;
    }

    if (!strcmpi(pszKey, "TRANSPORT")) {
        // .transport 1000,1000,0,0
        CPointMap pt;
        if (pt.Read(s.GetArgStr())) {
            Spell_Teleport(pt, true, false);
            return true;
        }
    }

    return false;  // Pass to parent
}
```

--------------------------------

### Default TUS Server Login Credentials

Source: https://github.com/sphereserver/source-archive/blob/main/0.55.403/graysvr/readme.txt

Predefined login credentials for the TUS server, found in the sample account file (TUSaccu.scp). These are 'Administrator' with the password 'Admin'.

```text
Login: Administrator
Password: Admin
```

--------------------------------

### Server Configuration and Startup

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

Changes affecting server configuration and startup processes. This includes replacing FREESERVER with ACCAPP=2 and ensuring proper IP monitoring.

```SphereScript
X FREESERVER replaced by ACCAPP=2
X .SERVIP should set the ONLY ip to monitor. 127.0.01 means monitor all ips.
```

--------------------------------

### TUS Server Script Files

Source: https://github.com/sphereserver/source-archive/blob/main/0.55.403/graysvr/readme.txt

Essential script files for the TUS server that need to be created or edited. These files manage account information, world data, and item/character definitions.

```ini
; TUSacct.scp: Account management file.
; TUSaccu.scp: Sample account file for initial login.
; TUSworld.scp: Contains world data. Must contain at least '[EOF]' if empty.
; TUSitem2.scp: Additional item definitions (create empty if needed).
; TUSchar2.scp: Additional character definitions (create empty if needed).
```

--------------------------------

### Item and Window Management

Source: https://github.com/sphereserver/source-archive/blob/main/coding_docs/packets/detailed_packets.htm

APIs for opening buy windows, renaming characters, and managing subservers.

```APIDOC
## 0x74 Packet: Open Buy Window

### Description
Opens a buy window for a vendor, displaying items available for purchase.

### Method
Not Specified

### Endpoint
`/sphereserver/source-archive`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cmd** (BYTE) - Command byte.
- **blockSize** (BYTE[2]) - Size of the block.
- **vendorID** (BYTE[4]) - Vendor identifier (can be combined with 0x40000000).
- **itemCount** (BYTE) - Number of items in the window.
- **items** (Variable) - Data for each item, including price, description length, and description.
  - **price** (BYTE[4]) - Price of the item.
  - **text_description_length** (BYTE) - Length of the item description string.
  - **item_description** (BYTE[text_description_length]) - The item's description.

### Request Example
```json
{
  "cmd": 116,
  "blockSize": "0010",
  "vendorID": "00001234",
  "itemCount": 1,
  "items": [
    {
      "price": "000500",
      "text_description_length": 15,
      "item_description": "A shiny sword\0"
    }
  ]
}
```

### Response
#### Success Response (200)
- **Details**: This packet is often preceded by `0x3c` (describe contents) and `0x24?` (open container) packets.

#### Response Example
```json
{
  "windowOpened": true
}
```

## 0x75 Packet: Rename Character

### Description
Requests to rename a character.

### Method
Not Specified

### Endpoint
`/sphereserver/source-archive`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cmd** (BYTE) - Command byte.
- **id** (BYTE[4]) - Identifier of the character to rename.
- **newName** (BYTE[30]) - The new name for the character.

### Request Example
```json
{
  "cmd": 117,
  "id": "00000001",
  "newName": "HeroOfTime...................."
}
```

### Response
#### Success Response (200)
- **Details**: Success response details are not specified.

#### Response Example
```json
{
  "characterRenamed": true
}
```

## 0x76 Packet: New Subserver

### Description
Defines a new subserver region with its location and boundaries.

### Method
Not Specified

### Endpoint
`/sphereserver/source-archive`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cmd** (BYTE) - Command byte.
- **xLoc** (BYTE[2]) - X-coordinate of the subserver's location.
- **yLoc** (BYTE[2]) - Y-coordinate of the subserver's location.
- **zLoc** (BYTE[2]) - Z-coordinate of the subserver's location.
- **unknown** (BYTE) - Always 0.
- **serverBoundaryX** (BYTE[2]) - X-boundary of the server region.
- **serverBoundaryY** (BYTE[2]) - Y-boundary of the server region.
- **serverBoundaryWidth** (BYTE[2]) - Width of the server region.
- **serverBoundaryHeight** (BYTE[2]) - Height of the server region.

### Request Example
```json
{
  "cmd": 118,
  "xLoc": "0100",
  "yLoc": "0200",
  "zLoc": "000A",
  "unknown": 0,
  "serverBoundaryX": "FFFF",
  "serverBoundaryY": "FFFF",
  "serverBoundaryWidth": "1000",
  "serverBoundaryHeight": "1000"
}
```

### Response
#### Success Response (200)
- **Details**: Success response details are not specified.

#### Response Example
```json
{
  "subserverDefined": true
}
```
```

--------------------------------

### Account Creation and Management

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

Handles account creation for players with 'bad accounts' by setting ACCAPP to 'Free'. Also addresses issues with GM rune usage and account password resets.

```plaintext
if loading worldfile with bad accounts- set ACCAPP=Free to auto create accounts.
Set random NEWPASSWORD for account. replaces the old one when used for the first time.
```

--------------------------------

### SphereServer Experimental Flags Configuration

Source: https://github.com/sphereserver/source-archive/blob/main/0.55.402/graysvr/manual.txt

Configures experimental server behavior flags that may affect compatibility. Use with caution, as some flags have specific platform limitations. For example, EF_UNICODE should not be used on Linux.

```ini
Experimental=	// Flags for options that affect server behaviour and which might affect compatibility
	00000001 // EF_DiagonalWalkCheck
	00000002 // EF_UNICODE		 (Don't use this on Linux, server will crash)
	00000004 // EF_CanSeeLOS
	00000008 // EF_Scripts_Ret_Strings
	00000010 // EF_New_Triggers
	00000020 // EF_New_Maps
	00000040 // EF_Scripts_Parse_Verbs
	00000080 // EF_Intrinsic_Locals
	00000100 // EF_Allow_Override
	00000200 // EF_Item_Strict_Comparison
	00000400 // EF_No_Pause_Packet
	00001000 // EF_WalkCheck
	00002000 // EF_AgeOfShadows
	00004000 // EF_DiagonalLOSCheck
Suggested value: Experimental=0404
Default value:	Experimental=00
```

--------------------------------

### Create and Manage Game Items (C++)

Source: https://context7.com/sphereserver/source-archive/llms.txt

This snippet illustrates the process of creating items, setting their properties, and managing their behavior within the game world. It covers item creation, property setting (name, hue, type, attributes), damage, durability, and placement in the world or containers.

```cpp
// Create item with specific ID
CItem* pItem = CItem::CreateBase(ITEMID_LONGSWORD);
if (pItem) {
    // Set basic properties
    pItem->SetName("Excalibur");
    pItem->SetHue(HUE_GOLD);
    pItem->SetAmount(1);

    // Set item type and attributes
    pItem->SetType(IT_WEAPON_SWORD);
    pItem->m_Attr |= ATTR_MAGIC;
    pItem->m_Attr |= ATTR_NEWBIE;  // Blessed

    // Set damage values
    pItem->m_itWeapon.m_attackBase = 30;
    pItem->m_itWeapon.m_attackRange = 10;

    // Set durability
    pItem->m_itArmor.m_Hits_Cur = 255;
    pItem->m_itArmor.m_Hits_Max = 255;

    // Place in world or container
    CPointMap pt(1000, 1000, 0, 0);
    pItem->MoveTo(pt);
    pItem->Update();

    // Or add to character's backpack
    CItemContainer* pPack = pChar->GetPackSafe();
    pPack->ContentAdd(pItem);
}

// Create container with contents
CItem* pChest = CItem::CreateBase(ITEMID_CHEST_METAL);
if (pChest) {
    pChest->SetType(IT_CONTAINER);
    pChest->MoveTo(pt);

    // Add items to container
    for (int i = 0; i < 100; i++) {
        CItem* pGold = CItem::CreateBase(ITEMID_GOLD_C1);
        pGold->SetAmount(1000);
        pChest->ContentAdd(pGold);
    }
}

```

--------------------------------

### Define a CxxTest Test Suite

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

Defines a test suite by inheriting from CxxTest::TestSuite and declaring public void member functions starting with 'test' as individual tests. Uses TS_ASSERT and TS_ASSERT_EQUALS macros for assertions.

```c++
#include <cxxtest/TestSuite.h>

class MyTestSuite : public CxxTest::TestSuite 
{
public:
   void testAddition( void )
   {
      TS_ASSERT( 1 + 1 > 1 );
      TS_ASSERT_EQUALS( 1 + 1, 2 );
   }
};

```

--------------------------------

### Configuration and Persistence Commands

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

Features commands related to server configuration and data persistence. .SAVEINI allows working with web pages for INI settings, and .SERVIP controls the IP address monitoring.

```SphereScript
.SAVEINI verb
.SERVIP should set the ONLY ip to monitor. 127.0.01 means monitor all ips.
```

--------------------------------

### Account Creation and Authentication in C++

Source: https://context7.com/sphereserver/source-archive/llms.txt

Handles the creation, authentication, and character loading for player accounts. It checks for existing accounts, creates new ones if auto-account creation is enabled, verifies passwords, and loads associated characters. Dependencies include the global account manager (g_Accounts) and configuration settings (g_Cfg).

```cpp
// Account creation and authentication
CAccount* pAccount = g_Accounts.Account_Find("username");
if (!pAccount) {
    // Create new account if auto-account enabled
    if (g_Cfg.m_iAccApp == 2) {  // AccApp=2 (Free)
        pAccount = g_Accounts.Account_New("username");
        pAccount->SetPassword("password");
        pAccount->SetPrivLevel(PLEVEL_Player);
    }
}

if (pAccount) {
    // Verify password
    if (pAccount->CheckPassword("password")) {
        // Load characters
        for (size_t i = 0; i < pAccount->m_Chars.GetCharCount(); i++) {
            CGrayUID uid = pAccount->m_Chars.GetChar(i);
            CChar* pChar = uid.CharFind();
            if (pChar) {
                // Add to character list
            }
        }
    }
}
```

--------------------------------

### TUS Server Configuration (TUS.INI)

Source: https://github.com/sphereserver/source-archive/blob/main/0.55.403/graysvr/readme.txt

Key-value pairs to be edited or added in the TUS.INI file to configure the TUS server. These settings control aspects like administrator email, client version, file paths, server identification, and web-related options.

```ini
; ADMINEMAIL= your email address for server reporting
; CLIENTVERSION= the current client version supported by TUS
; FILES= or MULFILES= path to Ultima Online game files
; SCPFILES= path to TUS scripts
; SERVNAME= server name for central reporting
; SERVIP= server IP for central reporting
; SERVPORT= server port for central reporting
; SPEECHFILES= location of speech files
; TIMEZONE= server timezone offset
; URL= your web page address
; WORLDSAVE= location of world save script files

; Web settings (optional)
; WEBPAGEUPDATE= update interval for web page in seconds
; WEBPAGEFILE= path and name of the web page
; WEBPAGEFILE2= path and name for a second web page
; WEBCLIENTLISTFORM= HTML form layout for client list
; WEBSERVERLISTFORM= HTML form layout for server list
```

--------------------------------

### JavaScript: Document Startup and Event Handling

Source: https://github.com/sphereserver/source-archive/blob/main/GrayWorld 10/graysvr/UpgradeLog.htm

This JavaScript code sets up an event listener to run a 'startupFunction' when the document finishes loading. It handles cross-browser compatibility for event attachment.

```javascript
var startupFunction = function() {
  linkifyElement("messages");
};
if(window.attachEvent) {
  window.attachEvent('onload', startupFunction);
} else if (window.addEventListener) {
  window.addEventListener('load', startupFunction, false);
} else {
  document.addEventListener('load', startupFunction, false);
}
```

--------------------------------

### Using TSM_ Assert Macros in CxxTest

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

Demonstrates the use of TSM_ macros for assertions within a CxxTest::TestSuite. These macros provide more detailed error messages than standard asserts, which is useful when common test logic is moved to helper functions. The example shows how to track which invocation of checkValue() failed.

```cpp
class MessageTest : public CxxTest::TestSuite {
public:
   void testValues()
   {
      checkValue( 0, "My hovercraft" );
      checkValue( 1, "is full" );
      checkValue( 2, "of eels" );
   }

   void checkValue( unsigned value, const char *message )
   {
      TSM_ASSERT( message, value );
      TSM_ASSERT_EQUALS( message, value, value * value );
   }
};

```

--------------------------------

### Configure CxxTest GUI with cxxtestgen

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This demonstrates how to specify different graphical user interfaces (Win32, X11, Qt) when generating test files using the 'cxxtestgen' command. The GUI displays a progress bar and writes results to standard output, which can be processed by IDEs. The `--runner` option can be used to format the output for specific IDEs like Visual Studio.

```shell
cxxtestgen --gui=X11Gui
cxxtestgen --gui=Win32Gui
cxxtestgen --gui=QtGui
cxxtestgen --runner=ParenPrinter
```

--------------------------------

### Runtime Control of CxxTest Abort Behavior

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This advanced feature allows dynamic control over whether tests abort on failure. The `CxxTest::setAbortTestOnFail( bool )` function can be called at runtime to change this behavior. The flag is reset after each test, but can be set in a `setUp()` function for suite-wide control. This functionality requires exception handling.

```c++
void CxxTest::setAbortTestOnFail( bool );

void MyTestSuite::setUp() {
    CxxTest::setAbortTestOnFail(true); // or false
}

```

--------------------------------

### Control CxxTest GUI Behavior (Minimized/Keep Open)

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

This explains how to modify the behavior of the Win32 and Qt GUIs. The '-minimized' command-line option starts the test window minimized, only showing it if an error occurs. The '-keep' option for the Win32 GUI keeps the window open after tests complete, allowing review of results.

```shell
-minimized
-keep
```

--------------------------------

### Visibility and Debugging Tools

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

Enhancements to visibility options and debugging tools. This includes the ALLSHOW command for seeing players on different map planes and the addition of AFK and spawn name tags.

```SphereScript
X Can't see players on other MAPPLANE(s) with ALLSHOW ?
X [afk] and [spawn] name tags in ALLSHOW and DEBUG modes.
```

--------------------------------

### Weighted Range Definition Example

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

This example provides the correct syntax for defining weighted ranges in scripts. Weighted ranges are used to determine probabilities or distribution of values, such as creature stats or item properties.

```SphereScript
{{ 0 10 } 5 { 34 500 } 3 0 10 }
```

--------------------------------

### 0x99 Packet: Bring Up House/Boat Placement View

Source: https://github.com/sphereserver/source-archive/blob/main/coding_docs/packets/detailed_packets.htm

This packet is used to initiate the placement view for houses or boats. It includes the deed ID and multi-model information.

```APIDOC
## 0x99 Packet: Bring Up House/Boat Placement View

### Description
This packet is used to bring up the placement interface for houses or boats. It specifies the ID of the deed being used and the multi-model information for the structure.

### Method
(Not applicable, this is a packet structure)

### Endpoint
(Not applicable, this is a packet structure)

### Parameters
#### Packet Fields
- **cmd** (BYTE) - The command byte.
- **request** (BYTE) - Indicates if the request is from the server (0x01) or client (0x00).
- **deedID** (BYTE[4]) - The ID of the deed for the house or boat.
- **unknown1** (BYTE[12]) - Reserved, typically all zeros.
- **multiModel** (BYTE[2]) - The model ID for the multi-part structure (e.g., 0x4000).
- **unknown2** (BYTE[6]) - Reserved, typically all zeros.

### Request Example
(Not applicable, this describes a packet structure)

### Response
(Not applicable, this describes a packet structure)
```

--------------------------------

### Executing MySQL Queries in C++

Source: https://context7.com/sphereserver/source-archive/llms.txt

Illustrates how to interact with a MySQL database using C++ within the Sphere server. It covers checking database connection status, executing SELECT queries to retrieve data, and performing INSERT/UPDATE operations. Requires the `_LIBMYSQL` preprocessor directive.

```cpp
// Using database queries in code
#ifdef _LIBMYSQL
CDataBase* pDB = g_Serv.m_hDb;
if (pDB && pDB->isConnected()) {
    // Execute query
    CVarDefMap query;
    query.SetStr("SELECT * FROM accounts WHERE username=?", false,
                 pAccount->GetName());

    if (pDB->query(query.GetKey())) {
        // Process results
        while (pDB->next()) {
            LPCTSTR pszEmail = pDB->getStr("email");
            int iLoginCount = pDB->getInt("login_count");
            // Process data
        }
    }

    // Insert/Update
    query.SetStr("INSERT INTO player_stats (char_uid, kills, deaths) VALUES (?, ?, ?)",
                 false, pChar->GetUID().GetPrivateUID(), iKills, iDeaths);
    pDB->exec(query.GetKey());
}
#endif
```

--------------------------------

### C++ typeid Operator for Runtime Type Identification

Source: https://github.com/sphereserver/source-archive/blob/main/coding_docs/language/typecast.html

Shows how to use the typeid operator to get runtime type information. It returns a constant reference to a std::type_info object, which can be used to compare types or get the type's name. This operator is defined in the <typeinfo> header.

```cpp
#include <iostream>
#include <typeinfo>

class CDummy { };

int main() {
  CDummy* a = new CDummy;
  CDummy* b = new CDummy;
  CDummy* c = nullptr; // Example for null pointer

  if (typeid(a) != typeid(b)) {
    std::cout << "a and b are of different types:\n";
    std::cout << "a is: " << typeid(a).name() << '\n';
    std::cout << "b is: " << typeid(b).name() << '\n';
  }

  // Example demonstrating typeid on a null pointer (will throw std::bad_typeid)
  // try {
  //   std::cout << typeid(*c).name(); 
  // } catch (const std::bad_typeid& e) {
  //   std::cerr << "Caught exception: " << e.what() << '\n';
  // }

  // Example demonstrating typeid on a valid pointer
  std::cout << "Type of a: " << typeid(a).name() << '\n';
  std::cout << "Type of *a: " << typeid(*a).name() << '\n';

  delete a;
  delete b;
  return 0;
}
```

--------------------------------

### 0x34 Packet: Get Player Status

Source: https://github.com/sphereserver/source-archive/blob/main/coding_docs/packets/detailed_packets.htm

This packet is used to request specific status information about a player from the server, such as basic stats or skills.

```APIDOC
## 0x34 Packet: Get Player Status

### Description
This packet serves as a request to the server for specific status information about a player. The 'pattern' field often indicates the type of information desired, with predefined codes for basic stats or skills.

### Method
Not Applicable (Packet Structure)

### Endpoint
Not Applicable (Packet Structure)

### Parameters
#### Packet Fields
- **cmd** (BYTE) - The command identifier for this packet (0x34).
- **pattern** (BYTE[4]) - A pattern, often 0xedededed, that may indicate the type of status requested.
- **getType** (BYTE) - A code specifying the type of information requested:
    - 0x04: Request Basic Stats (expecting Packet 0x11 Response)
    - 0x05: Request Skills (expecting Packet 0x3A Response)
- **playerID** (BYTE[4]) - The unique identifier of the player whose status is being requested.

### Request Example
```
// Example structure (conceptual, not actual request)
{
  "cmd": "0x34",
  "pattern": "edededed",
  "get_type": "04", // Request Basic Stats
  "player_id": "0000ABCD"
}
```

### Response
#### Success Response (200)
This packet is sent by the client to request player status from the server.

#### Response Example
```
// Example response structure (conceptual, not actual response)
// No direct response, this packet itself is the data transfer.
```
```

--------------------------------

### Manage Containers and Inventory (C++)

Source: https://context7.com/sphereserver/source-archive/llms.txt

Provides C++ functions for managing container and inventory systems. Includes adding items, searching for specific items by type or ID, counting items, and consuming resources from containers. Also covers backpack operations like adding items and checking weight capacity.

```cpp
// Container operations
CItemContainer* pContainer = dynamic_cast<CItemContainer*>(pItem);
if (pContainer) {
    // Add item to container
    pContainer->ContentAdd(pNewItem);

    // Add with specific position
    pContainer->ContentAdd(pNewItem, CPointMap(50, 50));

    // Find items in container
    CItem* pContent = pContainer->GetContentHead();
    while (pContent) {
        if (pContent->IsType(IT_GOLD)) {
            int iGold = pContent->GetAmount();
            // Process gold
        }
        pContent = pContent->GetNext();
    }

    // Count specific items
    int iTotal = pContainer->ContentCount(ITEMID_GOLD_C1);

    // Consume resources
    int iConsumed = pContainer->ContentConsume(
        CResourceID(ITEMID_INGOT_IRON),
        10  // amount needed
    );
}

// Backpack helper functions
CItemContainer* pPack = pChar->GetPackSafe();
if (pPack) {
    // Add item to backpack
    pChar->ItemBounce(pItem);  // Picks up item

    // Check weight and capacity
    int iWeight = pPack->GetTotalWeight();
    int iMaxWeight = pChar->GetMaxWeight();
    if (iWeight > iMaxWeight) {
        pChar->SysMessage("You are overloaded!");
    }

    // Search for item type
    CItem* pFound = pPack->ContentFind(CResourceID(ITEMID_BANDAGE));
}
```

--------------------------------

### Gas Trap Configurations

Source: https://github.com/sphereserver/source-archive/blob/main/GrayWorld 10/graysvr/items.txt

Specifies configurations for 'gas trap' entries. This section details the parameters associated with each unique gas trap setup.

```text
113a: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
113b: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
113c: 20,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
113d: 20,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
113e: 20,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
1145: 00,F00,00,01,Wff,L06,?00000000,A00000000,?0000,H00,'gas trap'
1146: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
1147: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
1148: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
1149: 00,F00,00,01,Wff,L00,?00000000,A00000000,?0000,H00,'gas trap'
```

--------------------------------

### Scripting: NUKE and TILE Functionality

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

Updates the NUKE and TILE commands to use the ALLSHOW functionality for determining the correct plane.

```plaintext
NUKE and TILE now use the ALLSHOW to determine what plane to use.
```

--------------------------------

### Command Line Options and Execution

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

Details changes to command execution and command-line options. This includes modifying CHARCMD to FUNCTION and the ability to use arbitrary commands with NUKE.

```SphereScript
change CHARCMD to FUNCTION and allow it to take one argument (number or string)
NUKE command can have an arbitrary command ex. .NUKE str 100 // will set str 100 to all in the area.
```

--------------------------------

### Command Line Testing with Script Files

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

This command-line argument allows developers to specify a particular script file for testing. This is useful for isolating and debugging changes within individual script files without affecting the entire server build.

```Shell
-Tscriptfilename.scp
```

--------------------------------

### Run CxxTest Tests

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

Executes the compiled CxxTest runner to run all defined tests and reports the results, indicating success or failure with details.

```bash
# ./runner
```

```bash
# ./runner
Running 1 test.OK!

```

```bash
# ./runner
Running 2 tests.
MyTestSuite.h:15: Expected (2 * 2 == 5), found (4 != 5)
Failed 1 of 2 tests
Success rate: 50%

```

--------------------------------

### 0x8C Packet: Connect to Game Server

Source: https://github.com/sphereserver/source-archive/blob/main/coding_docs/packets/detailed_packets.htm

This packet facilitates connecting to a game server. It contains the command, game server IP, game server port, and a new key.

```APIDOC
## 0x8C Packet: Connect to Game Server

### Description
This packet is used to establish a connection to a game server. It includes the command, the IP address and port of the game server, and a new session key.

### Method
(Not applicable, this is a packet structure)

### Endpoint
(Not applicable, this is a packet structure)

### Parameters
#### Packet Fields
- **cmd** (BYTE) - The command byte.
- **gameServerIP** (BYTE[4]) - The IP address of the game server.
- **gameServerPort** (BYTE[2]) - The port number of the game server.
- **newKey** (BYTE[4]) - A new key for the connection.

### Request Example
(Not applicable, this describes a packet structure)

### Response
(Not applicable, this describes a packet structure)
```

--------------------------------

### Login Procedures

Source: https://github.com/sphereserver/source-archive/blob/main/coding_docs/packets/detailed_packets.htm

Handles user login requests and server responses for login denial.

```APIDOC
## 0x80 Packet: Login Request

### Description
Submits a user ID and password for login authentication.

### Method
Not Specified

### Endpoint
`/sphereserver/source-archive`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cmd** (BYTE) - Command byte.
- **userID** (BYTE[30]) - The user's username.
- **password** (BYTE[30]) - The user's password.
- **unknown1** (BYTE) - An unknown byte, typically not 0x00.

### Request Example
```json
{
  "cmd": 128,
  "userID": "TestUser..................",
  "password": "SecurePass................",
  "unknown1": 1
}
```

### Response
#### Success Response (200)
- **Details**: Success response details are not specified. Assumed to be a successful login.

#### Response Example
```json
{
  "loginStatus": "pending"
}
```

## 0x82 Packet: Login Denied

### Description
Indicates that the login attempt has been denied with a reason.

### Method
Not Specified

### Endpoint
`/sphereserver/source-archive`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cmd** (BYTE) - Command byte.
- **why** (BYTE) - Reason for denial:
  - `0x00`: Unknown user
  - `0x01`: Account already in use
  - `0x02`: Account disabled
  - `0x03`: Password bad
  - `0x04` and higher: Communications failed

### Request Example
```json
{
  "cmd": 130,
  "why": 3
}
```

### Response
#### Success Response (200)
- **Details**: Indicates login denial.

#### Response Example
```json
{
  "loginStatus": "denied",
  "reasonCode": 3
}
```
```

--------------------------------

### CxxTest Assertion: TS_ASSERT_EQUALS

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

The TS_ASSERT_EQUALS macro verifies if two values are equal. It is a fundamental assertion for checking equality between variables or the results of function calls.

```cpp
void testSquare( void )
{
   TS_ASSERT_EQUALS( square(-5), 25 );
}
```

--------------------------------

### Compile CxxTest Runner

Source: https://github.com/sphereserver/source-archive/blob/main/56b/tests/docs/guide.html

Compiles the generated CxxTest runner source file into an executable using common C++ compilers like g++, cl, or bcc32.

```bash
# g++ -o runner runner.cpp
```

```bash
C:\tmp> cl -GX -o runner.exe runner.cpp
```

```bash
C:\tmp> bcc32 -erunner.exe runner.cpp
```

--------------------------------

### SCP Script Loading and Definitions

Source: https://context7.com/sphereserver/source-archive/llms.txt

Defines the main script loading index (spheretables.scp) and provides examples for item (i_custom_potion) and character (c_custom_dragon) definitions. Includes attributes like ID, NAME, TYPE, health, effects, sounds, and combat properties. Handles item usage on double-click and character creation/hit events.

```scp
// spheretables.scp - Main script loading index
[RESOURCES]
scripts/items/itemdefs.scp
scripts/chars/chardefs.scp
scripts/skills/skillmenus.scp
scripts/regions/britannia.scp
scripts/events/combat.scp

// itemdefs.scp - Item definitions
[ITEMDEF i_custom_potion]
ID=i_potion_greater_heal
NAME=Super Healing Potion
TYPE=t_potion
TDATA1=200  // Heal amount

ON=@DClick
    IF (<SRC.HITS> >= <SRC.MAXHITS>)
        SRC.SYSMESSAGE You are already at full health.
        RETURN 1
    ENDIF

    SRC.HITS += <TDATA1>
    IF (<SRC.HITS> > <SRC.MAXHITS>)
        SRC.HITS = <SRC.MAXHITS>
    ENDIF

    SRC.EFFECT 3,i_fx_heal_effect,2,15,1
    SRC.SOUND snd_drink
    SRC.SYSMESSAGE You drink the potion and feel refreshed.

    REMOVE

// chardefs.scp - Character definitions
[CHARDEF c_custom_dragon]
ID=c_dragon
NAME=Ancient Dragon
RESOURCES=10 i_meat_raw, 50 i_gold, 1 i_dragon_scale
FOODTYPE=t_meat
CAN=mt_walk|mt_fly|mt_fire_breath

STR={800 1200}
DEX={100 150}
INT={400 500}

SKILLMAKE=WRESTLING 110.0, TACTICS 100.0, MAGICRESIST 95.0, MAGERY 80.0
DAM=30,50
ARMOR=45

ON=@Create
    COLOR=colors_dragon
    FAME=15000
    KARMA=-15000

ON=@NpcRestock
    ITEM={1 3} i_treasure_high

ON=@Hit
    IF (RAND(10) < 3)
        ARGN1.EFFECT 3,i_fx_flamestrike,2,15,1
        ARGN1.DAMAGE {20 40},dam_fire
        SAY *breathes fire*
    ENDIF

```

--------------------------------

### Resource and Skill Make Definition in ITEMDEF

Source: https://github.com/sphereserver/source-archive/blob/main/55j/REVISIONS.txt

This snippet illustrates how resource requirements and skill-based crafting (SKILLMAKE) are now defined directly within the [ITEMDEF] blocks. This consolidates item-specific properties and replaces the older MATERIALS= and TEST SKILLNAME= syntax.

```SphereScript
[ITEMDEF 04573]
DEFNAME=GOLDEN_CHAINMAIL_COIF
RESOURCES=10 GOLD_INGOT
SKILLMAKE=BLACKSMITHING 28.6
```
Tokens:
Raw