Everyone

This Content can be viewed by everyone, even people with no account.

ALFA Release Notes v1.88

Change Log

IMPORTANT TO ALL MODULE MAINTAINERS: In this update, acr_time_i has changed. All quests with scripted cooldowns, and all functionality that relies on persistent time will have its timers set up, and will believe itself (just this once) to have fired several years in the future. This was due to a bug in the calculation of timestamps, which caused an integer overflow and correcting it may require a conversion. The tech team is available to apply these corrections if they become necessary.

General Fixes

  • Preception checks are now forcibly rerun after the use of default scripts to change faction (so that previous enemies won't continue to fight and become enemies again, for example).
  • Automated consumable crafting is less likely to produce the already-somewhat-rare free scrolls.
  • Changing combat modes with cooldowns will now function regardless of whether or not they've previously been activated.
  • Lingering effects from having Combat Expertise on while logging out should no longer be available.
  • Combat Expertise is more intelligent about updating when a user changes the contents of their hands.
  • Combat Expertise no longer informs your entire party when you've changed your tactics.
  • The skill focus feats for custom ACR skills now apply the bonus directly to the character, and should thus be more consistent in their function.
  • A series of bugs which came from the ACR accessing operating-system-level information (generally disabling cross-server communication and the player chat interface) are fixed.
  • Random spawn radius on the ACR Spawn System will now spawn the creature in a random spot inside the radius.
  • The architecture around applying damage over time for Vitriolic Blast will now more-reliably count the amount of damage to be dealt through multiple sequential castings of Vitriolic Blast (warlocks should expect only one damage over time to function at a time, but the most recent will be the one it counts from, whereas previously only about 1 in 3 would restart the timer).
  • The ACR Hotfix architecture has improved its architecture, and will no longer disable a server if it cannot apply the update (it will, instead, roll back and restart).
  • Messages sent to a player while they are offline will now be displayed after the PC has finished loading into the module, to make it more likely that the player sees that message.
  • acr_time_i now calculates all of its measures of time from real time in UTC, and provides a series of new functions that report in human-readable real time (rather than real time converted to game time).
  • acr_portal_cnd.ncs (not just .nss) is now in alfa2_acr.hak.
  • Subraces are less likely to be afflicted by movement rate bugs associated with changing appearance or swimming.
  • Many icons are fixed for scrolls of RP spells
  • The previously-advertised undead touch attack is now compiling in alfa2_acr.hak
  • Turn Undead works on any creature with levels in undead, even if that creature's racial type isn't undead.
  • DMFI item examine aborts-- instead of crashing the client-- if it can't find an item to examine.
  • All polymorph effects are removed as part of logging in, to prevent client crashes.
  • acr_vanity_i now uses a generic polymorph, instead of chickens, to prevent spell loss in spellcasters.
  • Raise Dead cast by a DM avatar-- as opposed to a possessed NPC-- no longer applies a level loss.
  • Favored Enemy: Beast can no longer be selected ("Beast" is not a canonical creature type. If you mean displacer beasts and unicorns, you want magical beast; if you mean dire bears and wolves, you want animal; if you want minotaurs, you want monstrous humanoid).
  • Nonlethal damage mode should no longer destroy existing damage penalties (e.g. from alchemical silver).
  • Trade Scrolls can be made from RP spells
  • Intimidate can now be rolled with chat dice. (#inti)
  • Tents and bedrolls can no longer be created during combat-- those who attempt to misuse them will instead be struck repeatedly by the metagame monkey.
  • Word of Recall is available as drd 8 / clr 6, not wiz 8/ clr 6. (wizards seeking to move about in this fashion should use Greater Teleport).
  • Wizards no longer have access to Stone Tell
  • When making an area transition into space near hostile monsters, characters now receive both a spot and a listen check.
  • Flee the Scene no longer sticks the user into a casting animation loop when used at less than the maximum range.
  • Forgery checks are no longer intercepted by fortitude.
  • Phat Lewt checks only allow one search check per person searching.
  • Calls seeking natural hair color are now more reliable.
  • Characters who are bleeding out will lose any standing invisibility effects, under the presumption that anyone who can dismiss invisibility would do so in order to provide healing.
  • Icons are provided for a number of scrolls.

Core System Changes

  • If a character's level is more than 8 higher than a target's CR, that target no longer provides combat XP.

Spell Changes

  • Jump now has a scripted function (providing a general bonus to the jump skill).
  • Glibness now has a scripted function (providing a general bonus to the bluff skill, but only inside of conversations; glibness cannot be used in conjunction with Feint).
  • Magic Weapon and Greater Magic Weapon can now affect monk gloves and ranged weapons (providing an attack bonus, rather than an enhancement bonus, to these; while there is little we can do about the damage discrepancy, this will allow users to pierce /magic damage reduction with these weapons).
  • Mass Camouflage is updated to its level and function from Complete Divine (drd/rgr 4, lasting 10 minutes/lvl).

New Spells

  • Dimensional Anchor is now available as a spell, and has a scripted function (stopping spells such as Etheral Jaunt, Etherealness, Dimension Door, and Flee the Scene).  

New Building Tools and Options

  • acr_tools_i has exposed a GetMasterSpellId() function, which may be used to acquire the source spell of one which was cast from a subradial (for instance, one might use this to tell that Protection from Evil came from Protection from Alignment).
  • The ACR has initialized a system which allows the tracking of effects and adjustments to characters through a PC Skin item. It is currently a fairly-weak system, but it lays the groundwork for future enhancements, correcting synergy bonus calculations, and providing skill foci for ALFA's custom skills.
  • acr_roll_i now contains ACR_Roll, which will roll arbitrary dice and return the result.
  • Feather Fall is available as an item property.
  • acr_hazards_i includes a series of functions which can handle movement and damage related to falling, as well as a series of functions to handle balance (obviously cooperating with the falling portion)
  • acr_environment_i shows the early implementations of functionality to track a region's temperature.
  • Our sample CLRScript project now has a workable sample constructor.
  • Area Transitions which are not two-way linked intentionally (e.g. one trigger, one door, two waypoints) may now have ACR_SAT_NO_WARN set as a local int to 1 to suppress the warning when using them.
  • ACR_GetArmorRulesType should be used instead of NWN2's GetArmorRulesType-- it is available in acr_tools_i
  • There are new KEMO chairs.
  • fx_icebody.sef is available from the core resources.
  • There are now appearance types for differently-sized dragons and lions (of note to builders that the appearance -type-, not its scale, determines the mechanical effects of size. Making a gargantuan creature 1/10th its size won't help its attack bonus or armor class, or make it appropriately vulnerable to tripping, without changing the appearance type).
  • zSpawn's random colors are once again random.
  • Logs will no longer present XP gain when there was none given.
  • Copies of the appearances for playable races with mechanical size set to tiny, small, medium, large, and huge are now available, labeled with (Size) after the names in the toolset. These are not yet attached to any other systems (such as enlarge or reduce person), but may be used for specific niche uses (e.g. fey, giants) now. These appearances do not change the scale of the creature, and they will still need to be manually set to look the size that they are.

New Features

  • #showstate now includes address information on servers.
  • ACR_CreatureBehavior has reached experimental state. Proficient scripters and builders may attempt to fenagle functional creatures out of them, but they remain officially unsupported.
     

Forums

ALFA Release Notes v1.87

Change Log

As a note to builders: there is a new release of NWScriptCompiler. Builders should pick it up for use in their building.

As a note to players of Warlocks: there are many changes to invocations in this update. However, this list should be taken as mostly-complete, and Warlock players can expect their class' mechanics to be much more stable going forward. However, the class is not in a high-enough-quality state to allow new characters to take the class, as some portions of its core mechanics remain fundamentally flawed and nearly unfixable.

General Fixes

  • The ACR will no longer allow characters with trailing spaces on their names to be created. 
  • The templates provided with automated crafting now distinguish between arcane and divine
  • Crafting prototypes should no longer appear in duplicate in the craft store.
  • The DMFI renaming tool allows 48 character strings, instead of 32
  • Svirfneblin should have less mysterious trouble swimming
  • Another instance of "Rick" claiming to be a kind of clicking has been removed from the load screens.
  • The "phat lewt" random loot system will now break the weak and fragile items, instead of the heavy and sturdy ones, when bashed.
  • Kuo Toa are closer to their canonical size (about 5' tall)
  • Putting containers in pChests should no longer result in duplicate items.
  • pChests are now less vulnerable to "sticking" open.
  • Automatically-closing doors now look for PCs on both sides of the area transition to see if they're ready to close.
  • NPCs are less prone to dropping excessively-valuable items when slain.
  • A missing music file imported from Icewind Dale is corrected.
  • Stores which are opened with the default NWN2 scripts no longer exibit any of the appraise-related misbehaviors.
  • Killing-related ACR quests will more frequently credit quest advancement if a party member kills the quest creature.
  • Adjusting the appearance of items no longer logs the adjustments as acquiring the item.
  • Changing appearance to a default player appearance no longer sets movement rate to "Slow." However, this does not prevent movement from being broken when changing appearance away from a standard character model-- only between them.
  • If a player logs in with a character with non-default movement, the ACR will automatically correct the movement. However, nwn2server will not recalculate the actual walk speed until the login following. A message explaining as much will be provided when this happens.
  • Weapons will no longer have -5 damage permanently stick on them after disabling subdual damage mode, and previously-bugged weapons can be corrected by equipping them and toggling subdual mode on and off.
  • Subdual Damage turns itself off when a player dies, and bugs of a rapid infinite loop of nonlethal damage fists being created and stripped no longer happen.
  • The subdual damage item property no longer changes the price of the item it's applied to.
  • Precise Strike and Insightful Strike now help subdual damage.
  • Favored enemy bonuses now apply in subdual combat
  • Bardic Inspirations are now treated more-consistently as songs, and now use a daily use of bardic music to activate and are mutually-exclusive with stealth.
  • Young dragons now occupy space and provide a selection GUI more appropriate to their actual size.
  • The ACR Spawn system now works with instanced areas.
  • Instanced areas assume that they need to clean themselves up after a minute of inactivity if no cooldown is specified.
  • Only player characters will count as party members when calculating XP.
  • Reports of the current date won't count the 10th day of a tenday as "day 0" it will correctly report as "day 10."
  • Quarantined characters no longer save to the central vault.
  • Swim actually applies double ACP, as it claims.
  • Swim triggers are better at picking the creature leaving on that event, and are thus less likely to prompt unexplained swim checks on people elsewhere on the server.
  • Many skill descriptions that had invalid text in them are corrected.
  • Darkvision may now be used successfully as an item property.
  • Combat Expertise and Improved Combat Expertise have taken many changes:
    • The armor class bonus provided by (Improved) Combat Expertise may no longer exceed the user's base attack bonus.
    • (Improved) Combat Expertise now provides Dodge AC, instead of Untyped, and thus offers no benefit when flat-footed.
    • (Improved) Combat Expertise is now disabled when casting spells or using spell-casting items.
    • (Improved) Combat Expertise now has a server-side-enforced cooldown of 6 seconds.
    • These changes should cover our standing enforcement issues with Combat Expertise and Improved Combat Expertise. Old orders about how the feats may be used and the penalties for their misuse are thus rendered null.
  • VFX provided by PC tools are now purged during casting of Wildshape, and associated crashes should no longer occur.
  • Forge Ring, Craft Rod, Craft Staff, and Craft Construct have their advertized caster level prerequisites.
  • There is no experience point reward for fighting a creature whose CR is less than your character level by more than 8
  • Wizards automatically learn the new cantrips as part of converting to the new ACR.
  • Sorcerers now gain cantrips on every odd-numbered level to a maximum of 9, instead of 6.
  • The additional availability of orisons may cause higher-level Favored Souls to acquire a couple orisons unexpectedly (there were previously 7 available, but the class was configured to allow up to 9).

Class Changes

  • Rangers now receive Endure Elements as a level 1 spell.
  • Favored Souls no longer receive Haste 3/day at level 17.
  • Though Song of Regeneration and Curse Song were banned long ago, they are removed from feat lists this release.
  • Clerics no longer get access to Control Undead
  • Cleric Domain spells are moved to align with the SRD / Forgotten Realms Campaign Setting / Player's Guide to Faerun where possible. Many of these spells are redundant compared to the typical spell list-- due to NWN2's generally-lax implementation of the domain spell slot, these spells are thus not very visible to clerics who use them.

Spell Changes

  • Word of Faith is split into Holy Word, Blasphemy, Dictum, and Word of Chaos, selecting the appropriate spell based on the caster's alignment when casting. Unlike Word of Faith, these spells are not party friendly, and they may not effect any target with more hit dice than the caster's caster level. Effects applied to targets now must satisfy a caster level requirement (HD <= CL - 10 for death; HD <= CL - 5 for severe effect; HD <= CL -1 for minor effect; HD <= CL for trivial effect). Duration for all effects is random, uneffected by caster level, and shorter for the more-minor effects, on the same pattern as the SRD implementation.
  • See Invisibility now lasts 10 minutes / caster level, instead of 1.
  • Devour Magic is now touch range and single-target only (previously targeted identical to Dispel Magic).
  • Beshadowed Blast now only applies blindness penalties once, and can be appropriately resisted by abilities like Blindsight (previously stacked direct penalties with the blindness effect, making it impossible to resist and doubling penalties on those who weren't protected).
  • The damage over time on Brimstone Blast is now dispellable, and does not stack with itself.
  • The damage over time on Vitriolic Blast is now dispellable, and does not stack with itself.
  • Dark One's Own Luck now only provides a bonus to the lowest saving throw of the caster (though it may be cast multiple times to cycle through the different saving throws), and its bonus is capped by caster level (previously +cha to all saves, no CL cap).
  • The Dead Walk now lasts 1 minute/ level (previously hour/level)
  • Chilling Tentacles no longer applies paralysis. It applies a combination of physical and cold damage, and attempts to grapple targets in the area of effect (previously all magical damage).
  • Entropic Warding's benefits against tracking no longer manifests as a bonus to stealth (previously +4 hide/ms).
  • Flee the Scene is now a short-range dimension door, operating by line of sight (previously 1 hour of haste).
  • Hellrime Blast now lasts 10 minutes, and does not stack with itself (previously 3 rounds).
  • Retributive Invisibility only stuns for 1 round on success (previously 3).
  • Tenacious Plague now creates actual swarms, which occupy space, do not move, and do not stack on top of themselves. Characters caught in a plague's swarm must make a fort save to resist nausea each round they remain; tenacious plague is not party friendly, but the swarms' placement will initially be based on the location of enemy targets (previously, it was a terribly-ineffective damage over time effect).
  • Utterdark Blast's negative levels now last one hour (not permanent).
  • Wall of Perilous Flame now does 2d6 + caster level damage when entered (previously 2d6 + charisma modifier) and 2d4 damage per round (previously 2d6 + charisma modifier)

New Spells

  • Waterbreathing (clr 3, drd 3, sorc/wiz 3, water 3)
  • Alarm (RP only)
  • Analyze Portal (RP only)
  • Animal Messenger (RP only)
  • Arcane Mark (RP only)
  • Arcane Sight (RP only)
  • Augury (RP only)
  • Calm Animals (RP only)
  • Commune with Nature (RP only)
  • Contact Other Plane (RP only)
  • Control Weather (RP only)
  • Create Food and Water (RP only)
  • Create Water (RP only)
  • Dancing Lights (RP only)
  • Delay Poison (RP only)
  • Detect Animals or Plants (RP only)
  • Detect Poison (RP only)
  • Detect Scrying (RP only)
  • Detect Snares and Pits (RP only)
  • Detect Thoughts (RP only)
  • Dimensional Anchor (RP only)
  • Discern Location (RP only)
  • Disguise Self (RP only)
  • Divination (RP only)
  • Feather Fall (RP only)
  • Force Cage (RP only)
  • Gate Seal (RP only)
  • Geas (RP only)
  • Ghost Sound (RP only)
  • Glibness (RP only)
  • Greater Scrying (RP only)
  • Greater Teleport (RP only)
  • Hide from Animals (RP only)
  • Jump (RP only)
  • Know Direction (RP only)
  • Lesser Geas (RP only)
  • Locate Creature (RP only)
  • Locate Object (RP only)
  • Longstrider (RP only)
  • Lullaby (RP only)
  • Mage Hand (RP only)
  • Magic Aura (RP only)
  • Mending (RP only)
  • Message (RP only)
  • Miracle (RP only)
  • Mislead (RP only)
  • Mount (RP only)
  • Nondetection (RP only)
  • Open/Close (RP only)
  • Pass without Trace (RP only)
  • Permanency (RP only)
  • Prestidigitation (RP only)
  • Purify Food and Drink (RP only)
  • Reincarnate (RP only)
  • Scrying (RP only)
  • Sending (RP only)
  • Speak with Animals (RP only)
  • Speak with Dead (RP only)
  • Speak with Plants (RP only)
  • Stone Tell (RP only)
  • Summon Instrument (RP only)
  • Telepathic Bond (RP only)
  • Teleport (RP only)
  • Tongues (RP only)
  • Tree Shape (RP only)
  • Tree Stride (RP only)
  • Undetectable Alignment (RP only)
  • Wall of Force (RP only)
  • Wind Wall (RP only)
  • Wish (RP only)
  • Word of Recall (RP only)
  • Zone of Truth (RP only)

New Controls and Settings

  • The ACR now includes an ACR_HEALTHMONITOR_GAMEOBJECTUPDATE_BACKOFF variable, which can be used to slow game object updates to slower than 600ms, should a server need to improve performance beyond the limits normally provided by the health monitor.

New Building Tools and Options

  • Spike Growth may now be tooled as a spell cast property
  • Shield may now be tooled as a spell cast property
  • There is an available include, acr_notifications_i, which allows builders to send a short message to a GUI off to the right of the screen, combined with a standard icon that reflects our typical depictions of warning / error / FYI / pointer. When clicked, these provide a more-verbose message box of variety that may be selected by the builder.
    • The recommended use for this is in things which are important enough to prompt player acknowledgement, but should not steal focus to do so. For example, spotting tracks as part of a static quest would be an appropriate use of this, as the server window might be too cluttered to notice the message, and if a fight is afoot, a modal form would be hazardous to the players receiving it.
  • There is now an ACR_AddObjectToSpawnPoint function available to explicity add something which was not created by the spawn system to a spawn point, so that it behaves as though it were spawned by the point (including despawning).
  • Vampire is now available as a subrace, to be used to assist in targeting vampire-specific abilities and effects.

New Features

  • DMs may now throw their voices through the typical chat interface. To do so:
    • First, select the creature who you wish to throw your voice to.
    • Enter # followed by a single-digit number 0-9 (for example, #1, #5). The NPC is then "anchored," and you will receive all the conversation it hears if you are out of range to hear it.
    • You may throw your voice to the NPC by using # followed by the number as a preface to send chat to the NPC (for example, #1 Hello world!)
    • PCs may not be anchored in this way.
  • Wizards may throw their voice to their familiars in the same way.
  • DM teams may specify other NPCs as valid to receive voice throwing from a player by specifying the local variable HENCHMAN_LEADER and giving it the value of the player's player ID (and this may be updated dynamically, if for example a player is helping characterize well-known NPCs during an event).
  • Players using a new GSID will be prompted to link their GSIDs to their forum accounts when logging in. The interface is simple, requiring just a click and a log in, and needs to be done only once per GSID.
  • Cross-server communication now allows messages to be sent to the IRC bot on behalf of a player in game.

New Models

  • Models for wings which are compatible with the various non-human-female character models are now available via the toolset.

  • Duodrones are now available as a creature appearance.

  • Hydras are now available as a creature appearance

New Loading Screen

  • Moradin now has a loading screen, which is visible to players of characters with either 10 intelligence or at least 1 rank in knowledge (religion).

Running scripts via IPC requests

Overview

Starting with ACR 1.87, servers support an IPC message type that allows a server to be directed to run a script in-game.  The run script request can come from another server, or from an external source that has database access, such as an external process or a website-driven activity.

Remotely executed script prototype

Scripts that are remotely executed follow a standard prototype:

void main(int SourceServerID, string Argument);

The SourceServerID argument specifies the server ID of the server that initiated the request. This may be zero if the request came from a source other than a server, such as website-based automation. The Argument argument supplies an optional, script-defined parameter provided by the party that created the run script request.

Note that no reliable acknowledgement semantics are provided; if acknowledgement is required, it should be implemented in the form of a reply run script IPC request initiated by the script that was executed (for which the SourceServerID may be used for routing purposes when generating a reply run script request).

Like other IPC requests, a run script request cannot be enqueued to a server that is offline (and will be discarded when the server starts up).

NWScript and C# APIs

From NWScript, a server can request that a script runs on another server with the ACR_RunScriptOnServer function, present in acr_server_ipc_i:

int ACR_RunScriptOnServer(int DestinationServerID, string ScriptName,
    string ScriptArgument);

The API requests that the destination server (whose ID is given by DestinationServerID) runs a script named "ScriptName" (without extension). The ScriptArgument value is passed to the script entrypoint according to the standard prototype.

From C#, the ALFA.ALFADatabase class provides an ACR_RunScriptOnServer API with the same prototype.  (If writing code in the ACR_ServerCommunicator module, the RunScriptOnServer method on the ACR_ServerCommunicator class can be used instead.)

In all cases, a caller must be prepared to deal with a request to run a script that is never processed (for example, the remote server could go offline).

Database record (server_ipc_events)

The server_ipc_events record for a run script request uses the following event code:

const int ACR_SERVER_IPC_EVENT_RUN_SCRIPT = 6;

The SourcePlayerID and DestinationPlayerID columns are not used for this request and must be set to zero. If the source of the request was a game server, its server ID must be listed as the SourceServerID, otherwise zero should be supplied. The destination server is listed as the DestinationServerID.

The EventText column is formatted as follows:

ScriptName:Argument

The :Argument portion may be omitted if the script takes no arguments. Note that the script name, colon delimiter, and argument must still fit within the 256 character limit of the EventText column.

Auxiliary database connections

Overview

Starting with ACR 1.87, there is support for setting up auxiliary database connections.  This support is intended for use if your module needs to connect to database servers other than the ALFA central database.

In most cases, you should use the standard ACR_SQL* APIs in acr_db_persist_i (or the ACR_Persist variable support) instead of auxiliary database connections.

Any number of database connections can be created by the API, but using a persistent connection setup at module startup time is strongly recommended (versus creating an destroying connections on the fly).  Connections do not need to be to the same server, and connections created to the ALFA central database are not synchronized with the acr_db_persist_i APIs (and should as a result be avoided).

 Usage

Auxiliary database connection functions are provided in acr_server_misc_i.nss.  The general workflow for an auxiliary connection is as so:

- First, a connection handle must be created via a call to ACR_CreateDatabaseConnection().  You must specify a MySQL connection string and, optionally, control flags (such as SCRIPT_DATABASE_CONNECTION_DEBUG to enable query logging to the server log).  This step is usually done at module startup, in a module init script. For an example of how to build a connection string, see CLRScript\ALFAMySQLDatabase.cs : ALFA.MySQLDatabaseInternal.SetupConnectionString. You should set the Max Pool Size to 1, and you will need to provide a way for script code to learn the connection settings for the database, such as via module variables set by the toolset, or hardcoded in script code (discouraged).

- Next, the connection handle (int) returned by ACR_CreateDatabaseConnection should be saved away, such as in a named local int on the module.

- When it is time to use the connection, retrieve the connection handle from where you have saved it (e.g. as a named local on the module object) and call an appropriate ACR_*DatabaseConnection API, such as ACR_QueryDatabaseConnection.  The API design mirrors that of the standard ACR_SQL* APIs, but with different API names.

API Reference (see acr_server_misc_i.nss in alfa2_acr.hak)

 

//! Create a database connection object.
//!  - ConnectionString: Supplies the database connection string.
//!  - Flags: Supplies connection flags.  Legal values are drawn from the
//              SCRIPT_DATABASE_CONNECTION_* family of constants.
//!  - Returns: A database connection handle, or 0 on failure.
//              The handle is used for subsequent database requests.  It
//              remains valid until explicitly destroyed via a call to the
//              ACR_DestroyDatabaseConnection function.
//
//              The handle can be saved as a module local variable, or in any
//              other convenient location where an int can be stored.
int ACR_CreateDatabaseConnection(string ConnectionString, int Flags = 0);

//! Delete a database connection created by ACR_CreateDatabaseConnection.
//!  - ConnectionHandle: Supplies the connection handle that was returned by a
//                       prior call to ACR_CreateDatabaseConnection.
//!  - Returns: TRUE on success.
int ACR_DestroyDatabaseConnection(int ConnectionHandle);

//! Execute a query.  The function is similar to ACR_SQLQuery.
//!  - ConnectionHandle: Supplies the connection handle that was returned by a
//                       prior call to ACR_CreateDatabaseConnection.
//!  - Query: Supplies the query string.
//!  - Returns: TRUE on success.
int ACR_QueryDatabaseConnection(int ConnectionHandle, string Query);

//! Fetch a rowset from the database.  The function is similar to ACR_SQLFetch.
//!  - ConnectionHandle: Supplies the connection handle that was returned by a
//                       prior call to ACR_CreateDatabaseConnection.
//!  - Returns: TRUE on success.
int ACR_FetchDatabaseConnection(int ConnectionHandle);

//! Get a column from a rowset in a database query.  The function is similar to
//  ACR_SQLGetData.
//!  - ConnectionHandle: Supplies the connection handle that was returned by a
//                       prior call to ACR_CreateDatabaseConnection.
//!  - ColumnIndex: Supplies the column index (zero for the first column).
//!  - Returns: The column value, or "" on failure.
string ACR_GetColumnDatabaseConnection(int ConnectionHandle, int ColumnIndex = 0);

//! Get the affected row count in a database query rowset.  The function is
//  similar to ACR_SQLGetAffectedRows.
//!  - ConnectionHandle: Supplies the connection handle that was returned by a
//                       prior call to ACR_CreateDatabaseConnection.
//!  - Returns: The count of affected rows.
int ACR_GetAffectedRowCountDatabaseConnection(int ConnectionHandle);

//! Escape a string for use in a database query.  The function is similar to
//  ACR_SQLEncodeSpecialChars.
//!  - ConnectionHandle: Supplies the connection handle that was returned by a
//                       prior call to ACR_CreateDatabaseConnection.
//!  - String: Supplies the string to escape.
//!  - Returns: The escaped string is returned.
string ACR_EscapeStringDatabaseConnection(int ConnectionHandle, string String);

 

 

ALFA Peer to Peer Server Network Protocol

Overview

Starting with ACR 1.87, ALFA servers have the ability to perform direct, peer-to-peer communication between eachother, bypassing the database.

Presently, this communication is only used for unreliable, datagram-oriented messages (which can be lost or reordered along the way), so it is only used for non-critical activities like advising a server that it should immediately retrieve an IPC message from the central database.  Datagram protocol messages are also unauthenticated, so drastic action shouldn't be taken on receiving them.

Network protocol

The protocol operates as multiplexed over the same data port as game data traffic, and thus requires no additional firewall configuration.

Each protocol message starts out with a standard header.  All fields are in little endian.  Code to operate on parsing and building network protocol messages lives in CLRScript\ALFANetworkMessages.cs, whereas code for sending and receiving actual messages with payloads lives in alfa2_acr.hak\ACR_ServerCommunicator\ServerNetworkManager.cs.

UInt32: Magic number.  This is used to distinguish ALFA protocol messages from standard game network traffic.  The magic number always has the value 0x414C4641 (the ASCII string "ALFA").

UInt8: Protocol type.  There only ALFA protocol type currently defined is PROTOCOL_DATAGRAM, with the value 0x00.  The datagram protocol provides unreliable message delivery (messages can be discarded or reordered along the way, so it can't be used for data that must arrive in one piece).  A future connection-oriented protocol that provided reliable semantics might have a different protocol id to allow the messages to be distinguished.

UInt16: Command.  This represents one of the protocol-specific command codes.

UInt32: Message length (includes the header described here).  This represents the length of the entire message.

Datagram protocol message commands

The datagram protocol defines several message command codes, which are listed below.

CMD_IPC_WAKE (0x0000)

This message is sent to a server in order to cause it to immediately query the database for IPC messages.  The purpose of the message is to work around the lack of a LISTEN / NOTIFY mechanism in MySQL for reliable IPC messages.  The actual IPC message(s) to process are stored in the server_ipc_messages table, whereas the IPC wake datagram simply causes the target server to check the table immediately.  This reduces the latency required for a server to respond to a message (servers normally periodically poll, so the IPC wake message eliminates the added latency from the polling interval if it was successfully delivered).

(Int32) Source server id.  The database id of the server that sent the message; the message should be discarded if the sending address doesn't match that server id in the servers table.

(Int32) Destination server id.  This should match the database id of the local server, otherwise the message should be discarded.

CMD_SHUTDOWN_NOTIFY (0x0001)

This message is sent from a server, to all online servers, when a server begins a clean shutdown (as started by the Restart Server tool).  The purpose of the message is to allow any future, connection-oriented protocol targetted at the server to be shut down.  Currently, no action is taken when the message is received.

(Int32) Source server id.  The database id of the server that sent the message; the message should be discarded if the sending address doesn't match that server id in the servers table.

CMD_NOTIFY_DATABASE_STATUS (0x0002)

This message is sent to inform one server of what the other server's view of the central database's health is.  In the future, it might be used to form a quorum that might try to diagnose whether a failure in connectivity to the central database is likely to be the result of a server-local failure, or a failure actually on the central database.

The #showstate debug command can be used to dump the database online status of each known server.  This can be used to try and manually diagnose whether a database connectivity failure is local or global.

Servers rebroadcast this message every 10 minutes.  In addition, if a server's connectivity state to the central database changes state, the message is immediately broadcast at that time.

(Int32) Source server id.  The database id of the server that sent the message; the message should be discarded if the sending address doesn't match that server id in the servers table.

(UInt8) Database online disposition.  This value is 1 if the sending server has a good connection to the database, else 0 if the sending server cannot connect to the database.

 

Syndicate content