Overview
The ALFA Encounter System provides an easy means for builders to add terrain specific random encounters to module areas. The system is a collection of creatures, scripts, and waypoints, built on top of the ALFA Spawn System, that allows a builder to easily add terrain appropriate random spawns. It is intended to be trivial to implement, and to decrease predictability for spawn groups in a given area.
 
The lowest logical unit is a creature. This is typically a single generic creature from an approved source such as Monsters of Faerun or the Monster Manual. You can spawn them individually in the DM Chooser for live play, but it is not recommended to use them within the toolset directly.
 
Above the creature is a creature group. A group is typically either a specific number of homogenous creatures, like a Kobold Gang EL 1 (1d6 + 3 kobolds), or a group of mixed creatures like an Orc Patrol EL 7 (1d4+4 orcs, 1d2 2nd level orc barbarians, and a 4th level orc leader). You can use these groups directly in your modules, but they can be predictable and subject to farming if the same group always spawns in the same place.
 
Above the creature group is a terrain group. A terrain group is a collection of creatures groups and single creatures appropriate for a given area. So for the Temperate Clear group, you might have a 10% chance of neutral animals, 10% militia patrol, 5% bandits, and so forth.
 
With a basic knowledge of scripting you can also use the predefined creature groups or terrain groups for your own custom areas, and you can modify or customize the scripts specifically for your server.
 
Usage
You will need to acquire the latest version of the ALFA Campaign folder, located here, or from a maintainer of the content (currently Ronan or Riotnrrd). Within the campaign folder is a full set of ALFA compliant creatures, along with a set of scripts and waypoints to spawn then in intelligent groups.
 
 
You will need to associate the ALFA-Campaign folder with your module from within the Campaign Editor plugin, then save, then reload to associate them with your module.
 
First, choose an area and terrain in your module to populate. Most areas conform to a loose climate zone; three examples might be temperate plains, southern mountains, or dungeon. Pick a terrain and difficulty that makes sense to you (for instance, you might choose ALFA_Groups->Dungeon->Dungeon EL 1-3 or Dungeon 4-6 for the upper and lower layers of a low level cave). Builders often place lesser dangerous areas close to major roads and towns, where more difficult areas would be in more remote areas. A good mix also ensures there are areas for PC parties of various levels.
 
Next, decide how frequent you want the creatures to be. A general guideline is a small area should have 1 active, a medium 2, and a large area 4, but you can increase or decrease if you like. By default, each individual spawn waypoint is active 50% of the time, but this can be changed by editing the placed waypoint ACR_SPAWN_CHANCE variable. You may want to keep the PCs guessing by dropping a number of waypoints to sum to your desired probability (1x50% spawn is active half of the time, whereas 3x33% chances would mean one would be active on average at a given time, or 8x25% would mean 2 would be active on average, etc). The spawn waypoints will reroll a chance to be active every 3 hours or so, and if destroyed will delay between 1 and 3 real life hours before having a chance to reactivate.
 
 
Finally, place the waypoints. In the Blueprints section, navigate to ALFA_Groups, then pick from Environment or Hostile or Defender spawns. For example, a Temperate Clear area would be ALFA_Groups->Environment->Temperate->Clear EL 1-5. Drop your waypoints away from ATs in sensible locations, and adjust the probability for your spawn waypoints with the ACR_SPAWN_CHANCE as desired. When you restart the server, you should see your creatures start to spawn.
 
 
Current Groups
Each terrain type has a default difficulty range. The Encounter Level (EL) of a spawn is generally appropriate for a party of 4 PCs of that level, so an EL 5 would be appropriate for a group of 4 5th level PCs. For above ground terrains, the difficulty is often higher at night.
 
ALFA_Groups->Defender (adventurers, dwarven or elven teams, halfling scouts, merchants, etc)
ALFA_Groups->Dungeon-> Dungeon - EL 1-3
ALFA_Groups->Temperate>Temperate Clear (EL1-5)
ALFA_Groups->Temperate>Temperate Hills (EL 2-9)
ALFA_Groups->Hostile (Animals, constructs, humanoids, lycanthropes, etc)
 
Technical Notes:
- Click on any waypoint and see the description field to determine the number and type of creatures spawned for that waypoint
- The waypoints use scripts defined in as_group_<name>. Examine the scripts to see how they are made
- To create your own encounters, you can copy a waypoint, and edit the ACR_SPAWN_GROUP_1 variable to point to your custom script. Then, copy any existing group script and save it with the name as_group_<new group>. You can then call other groups with any probability, or add your own creatures into the mix.

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.
   

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

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.

Links :

Sshfs installation

Public key authentification (for automatic reconnection)

Init script that will automatically mount the vault

Important configuration file that will automatically keep the vault connection alive

Installing Samba (if you need it)

Program for automatically starting VirtualBox on Windows.

 

Sshfs installation:

We first need to install sshfs

apt-get install sshfs

 

Then we need to create the local alfa user. 

Create a file with the following in it (replace XXXXX with a password for the alfa user):

cat > alfa.cred

alfa:XXXXX:1001:1001::/home/alfa:/bin/bash

Hit Ctrl-d

Then run:

newusers -r alfa.cred

 

First try to ssh to the central vault host:

ssh alfa@alandfaraway.org

Type in the alfa user password for the central vault (ask IA or TA if you don't know it).

 

Switch to user alfa (local user) :

su - alfa

Create the vault directory

mkdir vault

 

Switch back to root with a logout or ctrl-d.

 

Mount the vault (note you should do that only for testing as we have a better solution below that will automatically mount the vault when Linux starts):

sshfs alfa@alandfaraway.org:/home/alfa/vault /home/alfa/vault -o allow_other,reconnect

Type the alfa user password for the central vault.

 

Switch again to user alfa and try to create a file:

su - alfa

cd vault

cd test

touch test

ls -l test

 

If everything is okay the output of ls should look like this:

-rw-r--r-- 1 alfa alfa 0 Jun 27 21:24 test

 

Public key authentification:

In order to allow reconnecting you must allow public key ssh connections (ie allow to connect without typing the password):

 On the game server linux box as the user called alfa type in:

ssh-keygen -t dsa

(then type three times on return (ie default name for the file, no password, no password)

 

Then copy the public file over to the alandfaraway.org machine:

scp ~/.ssh/id_dsa.pub alandfaraway.org:gameserver.pub

(here replace gameserver with the acronym of your game server - e.g. whl)

 

Then connect to the alfa host:

ssh alandfaraway.org

(you'll still need to type the password here)

cat gameserver.pub >> .ssh/authorized_keys

(this will add the public key to the list of authorized keys)

exit

 

ssh alandfaraway.org

(this time you'll connect without needing to type the password).

 

In order for this to apply to the root user as well do the following:

Login as root using either:

sudo su -

or

su -

 

Create a .ssh directory if it doesn't exist:

mkdir ~/.ssh

Copy over the private key file:

cp /home/alfa/.ssh/id_dsa ~/.ssh/

And try to connect to the alfa vault:

ssh alfa@alandfaraway.org

(you should be able to connect without typing the password).

 

Init script for automatically connecting to the vault when Linux starts:

Here is a script that will automatically connect the vault when the Linux VM starts:

### BEGIN INIT INFO # Provides: sshfs # Required-Start:    $remote_fs $syslog $network # Required-Stop:     $remote_fs $syslog $network # Default-Start:     2 3 4 5 # Default-Stop:      0 1 6 # Short-Description: sshfs alfa # Description:       Automatically mounts the alfa vault using sshfs ### END INIT INFO   # Author: Patrice Torguet/Hialmar <torguet@gmail.com>   # Do NOT "set -e"   # PATH should only include /usr/* if it runs after the mountnfs.sh script PATH=/sbin:/usr/sbin:/bin:/usr/bin DESC="Automatically mounts the alfa vault using sshfs" NAME=sshfs DAEMON=/usr/bin/$NAME DAEMON_ARGS="alfa@alandfaraway.org:/home/alfa/vault /home/alfa/vault -o allow_other,reconnect,ssh_command=/usr/local/bin/alfa-sshfs-ssh" PIDFILE=/var/run/$NAME.pid SCRIPTNAME=/etc/init.d/$NAME   # Exit if the package is not installed [ -x "$DAEMON" ] || exit 0   # Read configuration variable file if it is present [ -r /etc/default/$NAME ] && . /etc/default/$NAME   # Load the VERBOSE setting and other rcS variables . /lib/init/vars.sh   # Define LSB log_* functions. # Depend on lsb-base (>= 3.2-14) to ensure that this file is present # and status_of_proc is working. . /lib/lsb/init-functions   # # Function that starts the daemon/service # do_start() {    # Return    #   0 if daemon has been started    #   1 if daemon was already running    #   2 if daemon could not be started      date >> /var/log/sshfs.log    echo 'trying to umount' | tee -a /var/log/sshfs.log    umount -l /home/alfa/vault || echo "umount failed with error code $?" | tee -a /var/log/sshfs.log    echo 'cleaning mount point' | tee -a /var/log/sshfs.log    [ -x "/home/alfa/vault_pbs" ] || mkdir /home/alfa/vault_pbs    rmdir /home/alfa/vault || mv /home/alfa/vault "/home/alfa/vault_pbs/vault`date +-%Y-%m-%d-%Hh%Mm%Ss`"    mkdir /home/alfa/vault && chmod a+rwx /home/alfa/vault    echo 'calling sshfs' | tee -a /var/log/sshfs.log    $DAEMON $DAEMON_ARGS || return 2    date >> /var/log/sshfs.log    echo 'sshfs done' | tee -a /var/log/sshfs.log   }   # # Function that stops the daemon/service # do_stop() {    # Return    #   0 if daemon has been stopped    #   1 if daemon was already stopped    #   2 if daemon could not be stopped    #   other if a failure occurred    echo 'umount' | tee -a /var/log/sshfs.log    umount -l /home/alfa/vault || return 1   }   case "$1" in   start)    [ "$VERBOSE" != no ] && log_daemon_msg "Starting $DESC" "$NAME"    do_start    case "$?" in       0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;       2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;    esac    ;;   stop)    [ "$VERBOSE" != no ] && log_daemon_msg "Stopping $DESC" "$NAME"    do_stop    case "$?" in       0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;       2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;    esac    ;;   status)        status_of_proc "$DAEMON" "$NAME" && exit 0 || exit $?        ;;   restart|force-reload)    #    # If the "reload" option is implemented then remove the    # 'force-reload' alias    #    log_daemon_msg "Restarting $DESC" "$NAME"    do_stop    case "$?" in      0|1)       do_start       case "$?" in          0) log_end_msg 0 ;;          1) log_end_msg 1 ;; # Old process is still running          *) log_end_msg 1 ;; # Failed to start       esac       ;;      *)         # Failed to stop       log_end_msg 1       ;;    esac    ;;   *)    echo "Usage: $SCRIPTNAME {start|stop|status|restart|force-reload}" >&2    exit 3    ;; esac   :

You have to put it in /etc/init.d (I have named it sshfs) and chmod it (chmod a+x sshfs).

Then type in:

update-rc.d -f sshfs defaults

This will add links in the rc.d directories.

 

Automatic keep alive of the vault connection:

This is a config file for ssh that will let ssh and sshfs send keep alive messages every 15 seconds. 

This file should be called "config" and be in root's .ssh directory.

Host * ServerAliveInterval 15 Host alandfaraway.info User alfa IdentityFile ~/.ssh/id_dsa Host alandfaraway.org User alfa IdentityFile ~/.ssh/id_dsa

 

SSH wrapper script for secure MySQL tunnel

The SSHFS connection is also used for connecting to MySQL securely.  You must place the following contents in a file at /usr/local/bin/alfa-sshfs-ssh .  That file will be referenced by the sshfs init script.

#!/bin/bash a=$@ shopt -s extglob ssh -g -L 3306:127.0.0.1:3306 ${a//-oClearAllForward*([^ ])?( )}

Make the script executable after you have pasted it in:

chmod +x /usr/local/bin/alfa-sshfs-ssh

If the Linux machine is directly connected to the Internet, specify the right interface for the port forward.  Make sure to set up firewall rules for allowing port 3306 inbound, too.  This should NOT be allowed inbound from the internet, just the local LAN (or Windows gameserver instance). 

 

 

Samba install/configuration

If you need samba to access the vault continue, if you don't (Windows VM hosted on a Linux OS) you can stop here.

Samba install:

apt-get install samba

 

Modify samba configuration file so that in the authentication part (it starts with ####### Authentication #######) you have the following uncommented:

security = user

 

And in the Home directory related part (it starts with [homes] you shold have :

read only = no

 

 After this you must do:

/etc/init.d/samba restart

 

On the windows machine you should now be able to type this in a cmd.exe:

net use z \\WindowsIP\alfa

 

VirtualBox auto start for Windows:

I have also managed to start the VirtualBox Linux VM using this:

http://vboxvmservice.sourceforge.net/

 

 

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);