15 Portals
Exits that let characters move quickly and easily around the world.
Virtual worlds often include "portals", which are exits that
jump large distances, or allow players to bypass parts of the
world that are so uninteresting they haven't even been designed.
For example: A city could be constructed as a number of interesting
districts, such as the shopping mall, city hall, and the park.
The residential neighborhoods might be uninteresting. What players
really want is a way to get around between the three districts, as
well as a way to exit the city.
For example: Everquest II has free water transport. At the end of
the dock is a bell. If the player rings the bell, they have a choice
of several destinations where they can be transported to. The
destinations are all far away.
In more technical terms, a portal is an exit that lets a
character quickly travel to any (known) maps in the region.
To make a portal exit:
-
Set pRoomPortal in the room where the exit occurs. Use
a number from 0 through 11, indicating a direction numbers, such
as 0 for north, 1 for north-east, etc.
-
Since portal exits are probably entry points to, make sure
to include the room in the map's pMapEntries.
See below.
Players (and NPCs) can use the portal to instantly move to any map
with known entry points.
See below.
To allow players to portal to a map:
-
Set the map's pMapEntries to all the rooms in the map
that can be entered. The rooms are usually the same as all the portal
rooms in the map, but not necessarily.
For example: If you have a cMapShoppingDistrict that's an east/west
street, then you will probably have exit portals at both the east and west
ends of the street. Likewise, pMapEntries will have two rooms,
one at the west end of the street, and one at the east end. Players
that "Travel to the shopping district" will automatically be
sent to the nearest room, east or west, depending upon where
they started from.
-
You may not want all maps to be instantly accessible by new players.
Many maps won't be accessible until the player character "learns" about
its existence from NPCs. To make a map that's unaccessible to new
players, include a factoid object in pMapEntries. When
the player character hears the factoid from a NPC, it should be
added to the player's knowledge list (KnowledgeAdd()). The next time
the player visits a portal, he will be able to access the new map.
For example: The city might also include "Mr. Feld's house". Since
the player character doesn't know of Mr. Feld's existence when the
begin play, "Mr. Feld's house" is never shown in any of the portals.
However, once a NPC gives the player a quest to rob Mr. Feld's house,
the player character's KnowledgeAdd() is called, and the map
can now be accessed through the portal.
Some advanced portal features are:
-
MapEntries() is the method that returns the pMapEntries
values. You might wish to write your own MapEntries() method for
special-case portals.
Example: You might want a one-off encounter to happen when a user
does, "Travel to distant city". There might be some bandits on the
road that are encountered once, but never again. To impliment this,
you'd write your own MapEntries() method for oMapBanditEncounter. If
the bandits have already been dealt with, this returns NULL.
If they haven't, it would return [[oRoomBanditEncounter, oMapDistantCity,
1.0]]. This would cause all travel to oMapDistantCity to be automatically
redirected to oRoomBanditEncounter.
16 Guard NPCs – Blocking access to doors
How to prevent characters from going through doors.
Guard NPCs - Blocking access to doors
Guards that prevent players from going through a specific door are a common
feature of IF. Basically, the player isn't allowed to pass until they provide
the right identification for the guard, speak a password (such as solving
the Sphinx's riddle), etc.
To make a guard object:
-
Write a ActionBlock() method for the guard object that
traps the "move" action and returns TRUE if the players try to
go through the door before providing proof of identity.
Make sure to test that the guard is conscious (pDamageUnconscious) and
alive (pDamageDeath).
17 Personal NPCs
Personal NPCs that are loaded when the player logs on, and unloaded when the player leaves.
Circumreality supports "personal NPCs". These are NPCs that are intended to
either hang out with the character (such as pets or henchmen), or
which are unique to each player character (such the the PC's family).
On a more technical note, a personal NPC is a NPC that is loaded
from the database only when the player character logs in, and which
is saved to the database when the player character logs out.
There are some exceptions to this, such as when the personal NPC
would have to be loaded into a room within a PC's instance when the
instance hasn't been created yet.
To make a personal NPC:
-
Using any method, such as "new cRaceElf", create a NPC.
Note: You cannot turn a MIFL-defined object into a NPC. This means
that if you cannot use the MIFL editor to create an object that
has the "Automatically create as an object" checkbox ticked, and then
turn it into a personal NPC.
-
Call PersonalNPCMake() to turn the NPC into a personal NPC.
That's it.
Once the object is a personal NPC, it obeys the following rules:
-
When the player logs on, all personal NPCs not in instances
will be loaded.
-
When the player enters an instance, all personal NPCs located
to the instance will be loaded at that time.
This means that a personal NPC in an instance is in stasis until the
instance is entered. If you want to have the NPC to continue to
act even if the PC isn't in the instance, then create a "quest" based
off cQuest. Assigned it to the PC. Either have the quest act as
the personal NPC's "brains" while the pesonal NPC is in stasis,
or (less ideally because its slow), keep the instance
loaded even when the PC isn't there using InstanceLoad().
-
When an instance is shut down and a personal NPC is in it,
the personal NPC will be saved. It will reload in the instance the
next time the player enters a copy of the instance.
This has some weird side-effects. If PC A joined PC B's party, and followed
PC B into an instance, then the instance would be assigned to PC B.
If PC A had a personal NPC that followed him, the personal NPC would
enter into PC B's instance too. If PC A left their personal NPC
in PC B's copy of the instance, and then logged off, his personal NPC
would disappear from PC B's instance. The next time PC A logs on and
enters a copy of the instance, perhaps PC C's copy of the instance,
the personal NPC will be loaded into PC C's copy, NOT PC B's.
You can ensure that personal NPCs will only be loaded into the
instance of their PC by setting pPersonalNPCOnlyPCInstances.
-
When the player character logs off, all his personal NPCs will log off.
-
If the personal NPC dies, and pPersonalNPCResurrect is
TRUE, then the NPC will be resurrected in the PC's (not the NPC's)
last save room, specified by pRoomResurrectionLocation.
-
If the personal NPC has pPersonalNPCPartyAuto set then
the NPC will automatically be included as a quasi-member of any
party that the PC joins; this is handy for creating pets and henchmen.
(This property is set when PersonalNPCMake() is called.)
For this to work, you will still need to include a goal
that has the personal NPC follow the PC around,
such as oAIGoalMoveFollowPersonalPC.
Some other functions, methods, and properties to know about:
-
pPersonalNPCs is a property in the player character that
is used to store the PC's list of NPCs.
-
Every personal NPC has pPersonalNPCFor set to the
PC to whom they belong.
-
pPersonalNPCPartyLast is the last time the personal NPC
saw his PC.
-
gPersonalNPCPartyAutoTime is the number of seconds that
the NPC is allowed to be away from the PC before it is no longer
automatically included in the PC's party.
-
PersonalNPCDatabaseCheckOut() will load a personal
NPC from the database so long as the room into which it should
be loaded exists.
-
PersonalNPCDelete() will dete a personal NPC.
-
PersonalNPCPartyAuto() is a method to test and see if
a personal NPC is in pPersonalNPCFor's party.
18 Replacing generic phrases
How to create more interesting writing.
Replacing generic phrases
Circumreality uses a lot of generic phrases, like "%1 (pick/pick/picks) up %2", from
sPerceiveMoveGet. These phrases get boring after awhile,
particularly when something signficant has happened. For example:
Instead of, "You pick up the jewel.", you might want to
have the computer say, "Eyes filled with green, you eagerly pick up up the jewel."
To do this:
-
Create a StringReword() method for your oJewel object (which is
picked up.)
You could alternatively create a StringReword() for the room that the
jewel appears in, or for the object upon which player characters are based.
For this particular example, the jewel object works best.
-
Write code for StringReword() that checks for sPerceiveMoveGet and the
use of oJewel. If these match, it returns the new string. For example:
if (IsList(Replace2) && (Replace2[0] == oJewel) && (String == sPerceiveMoveGet))
&tab;return "Eyes filled with green, %1 eagerly (pick/pick/picks) up %2.";
StringReword() is called by NLPStringFormat2(), so it
only works in cases where the string if being formatted
by NLPStringFormat2().
Circumreality also provides some other ways to reword generic phrases:
19 Custom commands for objects
Creating custom commands for objects.
Custom commands for objects
There are several ways to create custom commands:
-
Modify oParserVerb with your own commands. This works best when
creating commands that will be supported by a number of objects (of different
classes). See The "How command parsing works" tutorial for more information
on this.
-
In each object, write your
own NLPRuleSetTempVerbs() and NLPCommandParse() methods.
This is very flexible, but is a fair amount of work.
-
The easiest way is to use the ObjectCommandXXX() methods,
as described below.
ObjectCommandXXX() methods
The easiest way to add a custom command to an object is to
provide the ObjectCommandXXX() methods for the object (or the object's
class).
For example: You might want a special command to "Turn over the table",
perhaps because a secret message is written underneath.
To do this:
-
Come up with a lower-case string name for the action,
like "turnover".
-
Since the player must be able to access the bookshelf to turn it
over, prefix you name with "access", turning it into "accessturnover".
If the player only needed to see the object, then you'd
use "seeturnover", or "holdturnover" if the player's character needed
to hold the object.
-
Write your own ObjectCommandEnum() method for the table.
In this case, CommandList would merely have ["accessturnover",
"Turn over <object>", "flip *1"] appended.
"accessturnover" is the identifier for the command. "Turn over <object>" is
the primary command that's parsed, as well as the command that's displayed
in the object's context menu. "flip *1" is an alternate way of parsing
the command; you could leave this out in most cases.
-
Write you own ObjectCommandIsValid() method that returns
TRUE if it's passed a CommandID of "accessturnover".
-
Finally, write ObjectCommandAct() to actually flip the
table. This code might refresh the room's image with an upside-down table
and have the narrator speak something.
Design tip: Traditionally, interactive fiction titles have
huge problems with "guess the verb", where the player must (a) guess that
turning the table over will help solve a puzzle, and (b) guess the wording
for "turning the table over". Players don't like guessing
the verb! To be nice to the player, unless guessing the verb is very
important, always make sure to include important actions
in the object's context menu, by writing your own ContextMenuItemGet().
If you are using the ObjectCommandXXX() methods, then
you don't have to write your own ContextMenuItemGet() because
the commands will automatically be displayed.
20 Sending E-mail from an online IF file
Some information about sending E-mail that you should know.
Sending E-mail from an online IF title
When Circumreality is used for online titles, it likes to send E-mail to players
to notify them of:
-
Send "activation passwords" to the E-mail accounts supplied by
new users.
-
Alert players that their characters have received game-mail.
-
Warn players when their user accounts are about to be deleted because
they haven't been used for awhile.
For Circumreality to send E-mail, you need to fill in the following global variables:
-
gEmailAdministrator - The administrator's E-mail account that is
actually read, like "Fred@MSN.com". Occasional notifications may be E-mailed here.
-
gEmailDomain - The domain name where your E-mails are
being sent from. For example: If your automatic E-mails are sent
from "AutoMail@mXac.com.au" then the domain name would be "mXac.com.au".
-
gEmailSMTPServer - The SMTP server to send E-mails
through. If you don't know what this is, then look in Outlook Express
(or whatever E-mail you use), for your POP and SMTP server settings.
The SMTP name is for outgoing mail messages, and might look like
"mail.bigpond.com".
-
gEmailMailSendEmail - This is the E-mail associated with
your automatic E-mails, like "AutoMail@mXac.com.au".
Despite the "Do not reply to this mail" warning, People
will reply to automatic E-mails. You should occasionally check
your automatic E-mail's in-box and empty the messages.
-
gEmailAccessPasswordEmail - Like gEmailMailSendEmail,
except this is used when an access password is mailed.
-
gEmailServerName - Change this to the name of your
world, like "Fred's world at www.Fred.com". It will be included in
all automatic E-mails so players know which online IF title is
alerting them.
-
gEmailAuthUser and gEmailAuthPassword - Most E-mail
servers require that you provide an authorization user account
and password before they send E-mail. You may need to fill these
out for E-mail to be successfully sent. (You can look at the logs
to see if it was send successfully.)
-
gUserAccessPassword - Set this to TRUE to
require users to enter a valid E-mail address to access the online game.
You might also wish to change these:
-
gUserAccessPasswordValidTime - How long an access password will
be valid before the player needs to reapply. This defaults to 30 minutes.
-
sMailSendGameMailName - This is the friendly E-mail string
displayed instead of gEmailMailSendMail. You might wish to set this
to "MYWORLD automatic E-mailer", or something.
21 Rules of conduct and end-user license agreements
How to add rules of conduct or an end-user license agreement to your online game.
Rules of conduct and end-user licence agreements
It's fairly common for online games (MUDs and MMORPGs) to require that players
agree to a "Rules of conduct" or "End user license agreement (EULA)" before
they are allowed to play.
Circumreality automatically requires users to agree to rules of conduct before being
allowed to play. You can change the rules of conduct to suit your needs.
-
Change rLogonMainEULA to whatever rules of conduct you
wish to require.
-
Every time you change rLogonMainEULA, make sure
to change gEULAVersion to a new number. When gEULAVersion
is changed, all users (new and old) will be required to agree to
the new rules of conduct.
-
If you don't require users to agree to the rules,
then set gEULAVersion to NULL.
22 Linking to other worlds
How to link to another world.
You may wish to provide exits in your world that link to other
worlds. The character information won't be transmitted, but the
player will quickly be forwarded onto the new world.
To do this:
-
Create a <TitleInfo> resource for the other world.
When you create the resource, use the option in the resource
editor to load all the information from an existing link
file, such as MyWorld.crk.
-
When the user goes in a specific direction, enters a portal,
or presses a linking book, call LogOff() with the
<TitleInfo> resource.
23 Where to store your CircumReality files
Some tips about where to store your CircumReality files on your hard drive.
Where to store your CircumReality files
When you create a world using CircumReality, you'll probably end up creating
hundreds of different files, including MIFL libraries, 3D scenes, sound
files, etc.
My recommendation for how to store them is:
-
Create a directory on your hard drive, like "c:\WorldFiles".
-
Add a link to the "Startup" folder underneath "Programs" in the Start menu.
Have the link call "subst.exe w: c:\WorldFiles". What this will do
is remap the w: drive to c:\WorldFiles. (You'll need to reboot to have this
take effect, since the link is only run on start-up.)
This is handy, because if you decide to move your world files to a different
directory, you just change the "subst.exe" link and your
file dependencies won't be broken.
-
Within the w: drive, create sub-directories for:
-
Audio - Audio files are saved here.
-
Scenes - Save your "3D Outside the Box" scenes here.
-
Scripts - This is where you save for MIFL project file and
MIFL libraries.
-
Textures - Save texture bitmaps here.
-
Voices - Save your text-to-speech voices here.
Text-speech voice locations
The default libraries have several resources for the standard English
text-to-speech voices, such as: rVoiceFemale1, rVoiceFemale2, rVoiceFemale3,
rVoiceMale1, ..., rVoiceMale5, rVoiceNarrator, rVoiceMasterFemale1 ...
rVoiceMasterFemale3, rVoiceMasterMale1 ... rVoiceMasterMale5.
By default, these point to locations in "c:\program files\mxac\CircumReality".
You may wish to override these in the following cases:
-
If you only use a few of the standard voices, then override some of
the extra voices to point back at a voice you are planning to
use. Thus, if you're only using the first two female voices,
then modify rVoiceFemale3 to one of the text-to-speech voices
you used in rVoiceFemale1 or rVoiceFemale2. If you don't do
this then when the .crf file is built, it will include the third
female voice, making your .crf file larger than you need.
-
If you want to provide your own custom text-to-speech voices.
29 Sample work involved in creating a CircumReality Map
A "brief" list of the work required to create a CircumReality map.
Sample work involved in creating a CircumReality map
This is a list describing the work I undertook to create a CircumReality
map. The map, of course, is just a portion of the entire game.
-
Figure out roughly what happens in the map, why the players are there, etc.
-
Figure out what NPCs exist, why they're important to the players,
and how the NPCs interact with one another.
-
Determine what the map should look like, what buildings there should be, etc.
-
Using 3D Outside the Box, create the topography for the map.
-
Using 3D Outside the Box, create shells for buildings and other structures or
objects that affect room layout. These don't need to be detailed for now
since the important part it determining where the rooms go.
-
Create a cMap object.
-
(Optional) Create a grid of room objects using oRoomXXxYY, so that the room locations and
exits are automatically calculated.
-
For rooms in the grid, fine-tune the location
using pLocation, as well as automatic exits,
by setting pExitXXX to NULL.
-
Create non-automatic rooms, as per usual.
-
Create doors.
-
Revisit the room objects and assign them to special classes,
such as for indoors, near the beach, etc.
-
Make sure to set room flags like pProvidesLight and pRoomIsOutside.
-
Create NPC objects based on cRaceXXX for each of your NPCs.
Give them a pNameReal, pGender, and not much else.
-
Make sure the NPCs are maked as cSaveToDatabase so
they have a memory.
-
You may want certain merchants, using cMerchant, or guards
with pIsGuard.
-
Can the NPCs be attacked? Fill in pDamageCanBeAttacked.
-
Fill in the NPC's work and sleep schedules with
pAIScheduleLocationEat, pAIScheduleLocationLive, pAIScheduleLocationWork,
pAIScheduleTimeEat, pAIScheduleTimeSleep, pAIScheduleTimeWork.
If a NPC's schedule is critical then set pDontSleep.
-
Figure out what the NPCs do during the day and
write AIScheduleEnum(), AIScheduleGoal(), AIScheduleLocatio(),
and AIScheduleWhatDoing().
-
You may need to write some of your own goals based off
of cAIGoal.
-
Fill in the NPCs' relationships with pAIRelationships.
-
Create any objects that are important for the game,
as well as providing an examine description, pExamineGeneral.
Don't bother with custom artwork yet, leaving the pVisual blank
for many objects.
-
Likewise, create objects that the NPCs will carry.
-
Create books that expose backstory to players, cBook.
-
Some rooms will spawn hidden (or visible) objects.
Fill in pSpawnTime, pSpawnClass, pSpawnResourceTime, and
pSpawnResourceClass.
-
Allow NPCs to be given or shown objects using AIListenForActCmdOffer()
and AIListenForActCmdShow().
-
Create conversations scripts, based on cConvScript, for NPCs
to talk to one another as part of AIScheduleGoal(),
or chance meetings, using pAIConvScripts.
-
Some of the conversation scripts may reveal cKnowledge objects to
players that listen in, so you'll need to create some knowledge
objects at this point.
-
Create cKnowledge objects that the player can ask NPCs, and
then tell to other NPCs. Fill in pAIConvStories.
-
Have the NPCs respond to specific knowledge by
writing PerceiveKnowledgeSay().
-
Have the NPC respond to other player actions by
writing PerceiveXXX() methods. Some objects may prevent characters
from leaving the room, using ActionBlock().
-
Give NPCs skills, modifying pSkills.
-
Fill in pDescribed for the NPCs, rooms, and objects.
-
Fill in pExamineGeneral for NPCs, rooms, and objects.
-
Fill in pAIInfoSpeakXXX for NPCs, such
as pAIInfoSpeakFuturePlansNPC.
-
Does the NPC like gifts, or can the NPC be bribed? Fill in
pAIValueObject and pAIOfferCanBribe.
-
Create any story segments, based on cStorySegment.
-
What favors does the NPC grant once the NPC likes the PC? Changed pAIFavor.
-
Is player-vs-player combat (PvP) allowed? Set pRoomCanAttack.
-
Using 3D Outside the Box, and create models for your objects.
-
Place these models in a resource, and assign a pVisual property to
your objects.
-
Add details to your 3D Outside the Box scene, such as furniture, knicknacks,
and distant mountains (pMapMountains).
-
Using an administator account, use the "change my appearance"
and "change my voice" command
to create visuals for each of the characters. Then type in "appearance info"
to see the code for character's appearance voice, which
you can then paste into pVisualModifiers and pVoiceSub.
-
Record any sounds you might need, or find a sound library on
the internet.
-
Create ambient sound resources and place them in the world.
-
Create a custom text-to-speech lexicon using
the mXac NLP program included in 3D Outside the Box. Specify
the pronunciations of mispronounced words, particularly names.
Have your derviced
text-to-speech voices use the custom lexicon.
30 “Shipping” your CircumReality title
Goes through the steps necessary to "ship" a Circumreality title and put it online.
"Shipping" your Circumreality title
Once you have completed your Circumreality title, or
if you just want to distribute it to some friends so they
can try it out, you need to do the following:
-
Create a TitleInfo resource.
-
Generate and distribute your .crf or .crk file.
-
(Optional) Put your server online.
Create a TitleInfo resource
The "TitleInfo" resource provides information about the
interactive fiction title, such as whether it's run single-player
or as an online-game, the end user license agreement, and
a description of the title.
Every interaction fiction must have one TitleInfo resource
named rTitleInfo. The server library
comes with a default TitleInfo named rTitleInfo.
Therefore, if you will need to override it by creating your
own TitleInfo resource called rTitleInfo.
To do this:
-
Select the Add new resource menu item from
the Misc menu.
-
In the "Add a resource" page, press the TitleInfo button.
The title info "Modify resource" page will appear.
-
Change the name to rTitleInfo.
-
Press the Add button to add a resource for
a given language. You can have different TitleInfo resources
for each language, since you might wish to translate the
product description and end-user license agreement.
The "Title information" page will appear.
-
Type in the product's name, short
description, long description, and web site in the
first tab.
-
If the interactive fiction title can be run offline (without
requiring an Internet connection) then check the
item in the third tab allowing for this. Otherwise, uncheck
it.
-
If the interactive fiction title can be run over the Internet,
visit the third tab. See below.
-
Make sure to set the title's file name in the resource
to the same name that you'll be using for the link file. For
example, if you're distributing a "MyWorld.crk" link file,
then enter "MyWorld" for the filename. This
file name must be unique amongst all the worlds.
For the interactive fiction title to run over the Internet you'll
need to tell the editor what "shards" you'll have running.
A shard is copy of the world. If you don't have many users you'll
only have one shard. However, if you have thousands of users,
one computer may not be fast enough to handle all those users,
so you'll need run several servers, each one with a different
shard. (You could even run several shards on one computer.)
You can also use shards to provide subtly different experiences,
with some shards encouraging player vs. player activities,
while others encourage role playing. (See below.)
To add a shard (in the "Internet" tab):
-
Press the Add a new shard to add a new one.
-
Type in a name and description for
the shard.
-
Type in the domain name of the server, such
as MyIFServer.com.
If your server doesn't
have a domain name, but does have a fixed IP address
then type in the IP address, such as 12.34.567.89.
If you don't know either the name or fixed IP address,
the enter a website URL, http:://www.MyIFWebsite.com that
can be updated with the IP address; with this last option,
users will be asked for the IP address every time they run
your IF title. (By the way, when you run your server, the
main window will display the computer's IP address in
the title.)
If you have no clue about what I'm talking about then you'll
need to find a server provider to host your IF title. They'll
tell you all about domain names and IP addresses.
-
Type in the port your shard will be listening
to. If you don't know what this means then enter a number
between 4000 and 5000. (The only reason why a port would matter
is if another Internet application were using the same port
(unlikely) or another IF title or MUD were using the same
port (possible).)
-
Type in a parameter so that your code can
identify what shard it's running on. See below.
Each shard allows a "parameter" to be typed in. When the
shard is running, the software can access this parameter
by calling the ShardParam() call.
You can use the parameter to cause different shards to act
differently.
For example: You might want one of your
shards to allow player-vs-player combat. If you set your
shard parameter to "PvP" and then test (ShardParam() == "PvP")
to see if player-vs-player is allowed.
If the IF title is being run stand-alone, without any Internet
connection, then the ShardParam() call will return "offline"
If you wish to test your application with differnt ShardParam()
values, you can set the shard to test with on the first page
of the editor. When you first run CircumrealityWorldSim.exe (this application)
to edit your Circumreality project (.mfp) there's an option at the bottom
page for which "Shard number" you wish to use. Type in a
number (1 and up) for the shard number; ShardParam() will return
the value of that shard number. If you wish to test the offline
behavior then enter "0" into the shard number.
Generate and distribute your .crf or .crk file
Once you have entered your rTitleInfo resource:
-
Select the Compile menu item from
the Misc. menu.
-
Select the Test compiled code menu item from
the Misc. menu.
Running these menu options causes the editor to generate
a .crf and .crk file for you. The files are located in the
same directory as your main project file (.mfp). They have
the same name as your project file, but have different
extensions (with .crf or .crk on the end instead of .mfp).
If you wish your players to run your interactive fiction
offline you'll need to distribute the .crf file
on your web site. This is a large, and can
easily be hundreds of megabytes for a finished title.
A very small title will be more like 30 MB.
All your offline players need to do is install and
run the Circumreality client. When they're asked what interactive fiction
title to run they select the .crf file
your have provided.
The standard IF library works slightly differently between online
(over the Internet) and offline (on the local PC only) usage.
Throughout the library it checks for ShardParamIsOffline(); you
can search through the code for it. The offline parameter
causes the IF to act like an adventure game, while the online
is more like a MUD.
Here are some differences:
-
The offline game only allows one player at a time. Online
supports a thousand or more players.
-
When the player logs off, the offline version will automatically
shutdown the server. If online version will keep the server
running until another user logs on.
-
The offline code saves all the objects into a saved game
file using SavedGameXXX() function, and the master SaveGame()
function. The online code only saves the player characters
and the objects held by the player charaters; these are saved
in the database.
-
The offline code supports the "Save" command. Online does not.
Tip: If you want to run your IF server offline (without requiring
the Internet) but you wish it to act is though it were on
the Internet, then create a shard that connects to IP address
"127.0.0.1"... which is basically an IP address only available
within your computer.
If you wish your players to access your IF title over
the Internet (enabling multiple players to play in one world,
and providing extra protection against piracy), then
distribute the .crk file to them. This
is a small file (only a few KB). The only information it
stores is what you entered into the TitleInfo resource.
For your players to use it, they must download
the .crk file, and download and install
the Circumreality client. When they run the Circumreality client they need
to select the .crk file you distributed. If you have more
than one shard,they will be asked which shard to use,
and then the Circumreality client will connect to your server over
the Internet. It uses the domain name or IP address you
entered into the TitleInfo resource.
On your side, you must have a server (fancy term for a computer)
running and connected to the Internet. The computer's Internet
address must be the one provided in the TitleInfo resource,
which was also stored in the .crk file.
You then need to run the CircumrealityWorldSim.exe and have it run your
IF title. The best way to do this is to provide a command
in the "Run..." dialog (from the Windows Start menu) with
the following "c:\program files\mXac\Circumreality\CircumrealityWorldSim.exe"
-1 c:\MyIFFiles\MyIFTitle.CRF.
You'll need to replace c:\program
files\mXac\Circumreality\CircumrealityWorldSim.exe with whatever the full path
for the CircumrealityWorldSim.exe file is. The quotes around the
server's path are very important since they prevent the
operating system being confused by the space in "program files".
c:\MyIFFiles\MyIFTitle.CRF should be replaced
with the location of the .CRF file for your IF title.
The -1 tells the server to run using the
parameter for Shard #1. -2 will use Shard #2's
parameters, etc.
You will probably want your server to run the command line
as soon as it starts up, so that even if the server reboots
your IF title will be running.
That's it.
If you just want to do a quick test with some friends,
and don't have a dedicated server for your IF title:
-
In the TitleInfo resource, create a shard
whose address is a bogus web site, such
as http://www.NotARealWebSite.com.
-
Go through all the compiling and distribute
the .crk file to your friends.
-
When you wish to test your IF, connect
to the Internet and run CircumrealityWorldSim.exe from
the command line, as from above. Make sure the shard number
in the -1 points to the shard with the
bogus web site.
-
When the Circumreality server window appears, it will display the
server's IP address in the title. It will be a number
separated by periods, like 12.34.567.89.
If the listed IP address is 127.0.0.1 or 0.0.0.0 then
the server either couldn't connect to the Internet or (for whatever
reason) wasn't able to get the computer's IP address.
Retry and hope it works, or you're out of luck. (Although there
are ways to get the computer's IP address from the network control
panel and other applications. You can
also try http://www.WhatIsMyIP.com)
-
Call your friends and tell them to run the client on their
computer. When they select your special shard (with the
bogus web site) they'll be asked for an IP address. Have
them type in the IP address from the server's title.
They should connect to your server.
NOTE: If you turn off your computer (or log off the Internet),
your IP address will probably be different the next time you
log on.
31 Getting your world hosted by a third party
The effort needed to get your world hosted third party.
Getting your world hosted by a third party
The chances are that you won't want to leave your computer up
and running all the time, nor will your ISP like you using several
hundred gigabytes of bandwidth a month.
To find a host, you should google for "virtual private server" (or "VPS"),
"hosting", "private server", "dedicated hosting", etc.
For my part, I chose www.Prohosters.com. As of writing this, I've only
used them for a few days, so I can't really give an opinion other
than their product support personel have been very helpful so far.
I decided to use them because they were mid-priced; I'm always
wary of the cheapest products.
From Prohosters (and others), you have two choices:
-
Dedicated server - A computer is set aside specially
for you. Only your software is running on it. This is the ideal
solution, but it's also expensive, $200+ per month (as of this
writing). If you were expecting hundreds of simultanous players,
this would be a requirement.
-
Virtual private server (VPS) - In a VPS, you share one
computer with many other users, sometimes as many as 60.
The up-side side this that VPS's
are affordable for amateurs, starting at around $50 per month.
Unfortunately, you have less memory and CPU since the computer's
resources are shared amongst all the users. This isn't an issue
for amateur worlds since you'll be lucky to have 50 players online
at once.
However, one annoyance with VPS servers is that with 60 users,
there's a much greater chance of a server crash.
This means that your world won't have 99.9% up-time. Again,
amateur worlds can get away with downtime, but professional
ones cannot.
I chose prohoster's $70/month package to start out with. It's
a Windows 2003 server running Plesk. It provides me with 256 megabytes
of RAM (up to 1 gigabyte burst RAM), 10 gigabytes of
storage, 500 gigabytes of bandwidth. Under this plan, one server is
divided amongst 30 users.
My guestimate is that such a package would support 25-50 simultaneous
players, which is plenty for an amateur world, or for my
initial test world.
Here's a general idea of what your hosting service needs to
offer, for an amateur world:
-
Windows 2003, XP, or Vista.
-
256-512 megabytes RAM assigned to you. 5-10 gigabytes of hard drive.
About one-tenth to one-fifth of a CPU-core. The Prohoster machine seems to have
four processors, divided by 30 users, is about 13% of a CPU core
per user.
-
SMTP (and E-mail) server since CircumReality will send E-mail to
players when the receive in-game mail. You don't need to have the same
service providing the E-mail though. This seems to be a standard option.
-
Access to the server via Windows' Remote desktop connection. This
seems to be a standard option.
-
The ability to have the CircumRealityWorldSim.exe program automatically
restart if the server reboots; this is particularly important for VPS (cheaper)
servers since they seem to reboot every few days. Windows comes with this
functionality built in, and it should be standard for hosting services.
-
A domain name, like www.MyWorld.com. You don't really need this
since CircumReality will also work with just an IP address. Domain names
are standard.
CircumReality sends E-mail to players to notify them when they get in-game
mail, when their user accounts are about to be automatically
deleted, and when players forget their password.
For this to work you must:
-
Set up an E-mail server. Hosting services assume that people
will automatically want their own E-mail servers when they subscribe,
so E-mail is a given.
Unfortunately, setting up an E-mail server isn't necessarily as easy
as it should be. ProHosters uses Plesk. In Plesk, I can to create assing
my IP address(es) to the IP pool, and then create a "domain" that was
associated with one or more of the IP addresses in the pool. Then I had
to create an E-mail account, which didn't work right away... but
product support got it working eventually.
Once you set up your E-mail server, you need to find out the address/name
of the SMTP server, and your SMTP-authentication name and password.
(SMTP is "Simple mail transfer protocol" for sending mail, not receiving it;
POP is for receiving, but CircumReality doesn't recieve E-mail, only sends
it.)
This information is the same stuff you type into Outlook Express (or
whatever E-mail program you're using) under the "Accounts" option.
-
Once you get all the right addresses for your SMTP server, you
need to set the following globals: gBugEmailAddress, gBugMailToCharacter,
gEmailServerName, gEmailAccessPasswordEmail,
gEmailMailSendEmail, gEmailSMTPServer,
gEmailDomain, gEmailServerName, gEmailAuthUser, and gEmailAuthPassword.
This might be a good point to set gEULACompanyName with your company's name,
You also need to set the string, sMailSendGameMailName.
You need to create a TitleInfo resource to override the default one,
rTitleInfo. (It must use the same name too.)
The resource contains a lot of information about your world, such as
its name, a description of it, and a background picture.
As far as this tutorial is concerned, what's really important is that you
need to create a "shard" entry that lists the domain for your server.
-
In the TitleInfo resource editor, click on the "Internet" tab.
-
If a shard isn't already listed, then press Add a new shard.
-
Type in a name for the shard. If your game only has one shard then
this doesn't really matter because players won't see it.
-
Type in a short description for your shared. Again, this is
only important if you are going to run more than one shard.
-
Type in the server. This is important, since without
it CircumReality won't be able to locate your server. This the the domain
name that's associated with your server, such as www.MyGame.com. Of course, you'll
have to pay someone to reserver this name, probably the same
company that provides your server.
-
Type in the TCP/IP port. If you don't know what this is, or don't
care,then leave it at its default, 4000.
-
Type in a parameter that will be accessible through ShardParam(). This
is only necessary if you are running more than one shard.
Build your .crf (and .crk) files
You must build a .crf and ,crk file:
-
In the "Misc" menu, select "Compile".
-
In the "Misc" menu, select "Test compiled code".
-
A "CircumReality World Simulator" window will appear. It's
not important now. Close it.
Look in the directory where you store your project file, such as
"w:\Scripts\MyProject.mfp". In that same directory, you'll find
a newly-created "w:\Scripts\MyProject.crf", and
"w:\Scripts\MyProject.crk". Copy these someplace safe.
Then, upload both the .crf and .crk files to a FTP
server that your hosted world-server can access. The easiest option
is to upload them both to your world-server's FTP site. (How you
get FTP working on your server is another issue.)
The .crf file contains all the data and script necessary to
run your world, as is probably 100 megabytes or more. The .crk
file should be small, around 50 KBytes, and is the file you hand
out to players who want to enter your world.
To start your world (on your hosted server), you need to do the following:
-
Run "Remote desktop connection". It's hidden under
your Start menu, in Programs, Accessories, Communication.
-
You'll need to type in your server's domain as
well as the account and password to long in is.
Your domain will be www.MyGame.com, or whatever domain you've
chosen. The account will probably be "Administrator", but not
necessarily. The password will have been chosen by you
at some point. ProHosters uses Virtuozzo, which lets you
set the log-in password.
When you do successfully log in, your desktop will be replaced
by the desktop on your remote server. At the top of the screen
is a small toolbar listing the server name and providing
buttons for minimize and close.
-
On your remote server, download and install CircumReality from
www.CircumReality.com.
-
On your remote server, either download MyProject.crf or
find where FTP stored it on the sever by searching for MyProject.crf.
-
Copy MyProject.crf to c:\, or some directory of your
choosing.
-
Open the "c:\program files\mXac\CircumReality" directory,
or wherever CircumReality was installed.
-
Run CircumRealityWorldSim.Exe.
-
Press Dialog.
-
Open up c:\MyProject.crf or whatever you used.
-
Press the Open (and run) button.
The "CircumReality World Simulator" window will appear. Your world is live!
To make sure your world is working:
-
On your local computer (not your server), run CircumReality.
-
If you have a password file then use that, otherwise create one.
-
Press Try playing in a new world.
-
In the world-selection page, find "w:\Scripts\MyProject.crk"
(not the .crf file) and open it.
Within a few seconds, you should be connected to your world.
-
You can verify this by switching to the remote desktop and
check that the "CircumReality World Simulator" shows a connection.
If you can't connect, then try the following:
-
Make sure you have the right domain name in rTitleInfo.
It should be www.MyGame.com, or whatever you told the server company.
-
From the command line, type "ping www.MyGame.com". It should
say that it worked; if it didn't then you need to talk to your server
provider.
-
The ping command will display an IP address for www.MyGame.com. This
should be the same as the IP address shown by the
"CircumReality World Simulator" running on the server (accessible through
the remote desktop). If it isn't then talk to your server provider.
Another thing to check is that the CircumReality World Simulator can send out E-mails:
-
Run CircumReality from your local computer. You should already
have an entry in your password file for "My project".
-
Before clicking on the "Play My Project" button, hold down the control
key. Then click on the button, then release the control key.
This will log you on, but won't immediately go to play. Instead you'll be presented
with a few options, one of which is "Change personal information".
-
Press Change personal informatiion
-
Type in your E-mail address if it isn't already typed in.
-
Press E-mail password.
Check your E-mail account a minute later. You should have received an E-mail with
your password.
If you didn't, then something isn't set up properly with your
E-mail server. Check the following:
-
Set up Outlook Express (or your E-mail program) to use the POP and SMTP settings
for your E-mail server. Try sending an E-mail from your server's E-mail
account to your main E-mail account. If this doesn't work then see
your server company's support staff for help.
-
Make sure that gEmailAuthUser, gEmailAuthPassword, etc. are
entered properly.
-
Assuming that you saved your .crf file as "c:\MyProject.crf" on the
remote server, switch to "c:\MyProject" on the remove server.
In the directory you'll find one or more files that look like,
"log2007032621.txt". These are log text files. You'd normally access them
from an administrator account in CircumReality, but since since you already
have the remote desktop opened, this is just as easy.
-
Find the most recent logXXX.txt file and double-click it to
open it with notepad.
Scroll down the the bottom of the text file, and look for text indicating that
E-mail was set. For example: Search for "SMTP" or "Domain" in the text.
Read then next 10-20 lines and look for some indication about what type of
error occurred.
Create the main administrator account
By default, the first person to log into the world and create the user-name,
"Administrator", as well as the character name, "Administrator", gets special priviledges.
(You can change these defaults.)
Therefore, you must create an "Administrator" user account, and an
"Administrator" character within that account:
-
Run CircumReality, and then select and type the password for your password file.
-
Press I have an existing user acount in a world.
-
In the world selection page, select w:\Scripts\MyProject.crk (not the .crf file).
The "Account view/edit" page will appear.
-
Under Name, type "Administrator account", or something that's easy to identify.
-
Under User name type in "Administrator".
-
Under Password type in a password. Make sure not to lose it.
-
Press Back.
-
Press "Play Administrator account".
You will log into your server.
-
When asked for your character's name, type in "Administrator".
That's it.
The server is guaranteed to reboot at some point. If you are using a virtual
private server, it'll probably reboot every few days. To handle this circumstance:
-
On the server (using the remote desktop), Find a select the
"Schedule Tasks" option. In Windows, you'll normally find it
under the Start menu, Programs, Accessories, System Tools. In the ProHosters
server I was given, it was underneath "Control panel".
When the "Schedule Tasks" list appear, it will show a list of
scheduled tasks, along with an option for "Add scheduled task".
-
Double-click Add scheduled task.
-
The "Scheduled task" wizard will appear. Press next to
get to the application-selection pane.
-
You'll be shown a list of applications. Unfortunately, the right one
isn't on them. Instead, click Browse.
-
Find the "c:\program files\mXac\CircumReality" directory (or
wherever you installed) and select CircumRealityWorldSim.exe
by double-clicking it.
-
The wizard will ask you when to perform the task. Clik on
"When my computer starts" and press "Next".
-
You'll then be asked for your user name and password. This
is the user name and password that you used for the "Remote desktop
connection" program. Press Next.
-
In the last pane, you'll be given an option for "Open advanced properties
for this task when I click Finish". Check this.
-
Press "Finish".
A new window wil appear with three tabs, "Task", "Schedule",
and "Settings".
-
In the "Task" tab, append " -1 c:\myProject.crf" to
the "Run" line. After doing this, the line will probably
be, ""C:\Program Files\mXac\Circumreality\CircumrealityWorldSim.exe"
-1 c:\myProject.crf"
-
In the "Settings" tab, make sure "Stop the task if it runs for:"
is unchecked
-
Press OK.
You won't find out if this works until the server reboots and players start
E-mailing you that the server is down. Some potential ways
this can fail are:
-
You mistyped something in the "Run" edit field. You can
test this by copying the line to the clipboard, press the Start menu,
then "Run...", pasting in the text, and pressing "OK". If
the "CircumReality World Simualtor" doesn't appear a few seconds later
then you probably have a typo. (Make sure that any running versions
of the world simulator are shut down before trying this.)
-
You may have typed in the wrong user and password.
-
The scheduled task may not have gone off, perhaps because of permissions
that the hosting company has set. Talk to their product support staff
for help.
Detecting failed reboots and crashes
You can run a monitoring application to make sure that the CircumReality
server is running properly. To do this:
-
On the sever, using "Remote desktop connection, run CircumRealityWorldServer.exe.
-
Press the Set up the monitoring mode parameters button at
the bottom of the page.
-
Press the Dialog for "World #1" and use it to find
the .crf file, like "c:\myProject.crf".
-
Type in the Shard number for world #1, which is probably "1".
-
If you're running any other worlds on this server, repeat.
-
Fill in all the Email info on the page. It's exactly the same information
that you used to send notification E-mails from the server.
-
You might want to uncheck "E-mail even if it's all running properly" after
you have the system working. Leave it checked for now so that you know it's working.
-
Close the window.
-
Test that the program works by
running "c:\program filex\mXac\CircumReality\CircumRealityWorldSim.exe
-monitor". It should run the monitoring application, potentially start up the
server, potentially send E-mail, and then shut down.
-
As in "Handling re-boots", create a timer. However, make this
timer run once and hour (or so), and have it
run "c:\program filex\mXac\CircumReality\CircumRealityWorldSim.exe
-monitor".
Exiting the remote desktop by staying logged on
That's it! Your world is running. One important note:
-
When you close the "Remote desktop connection" window, you will stay logged
onto Windows (on the remote computer). This is good. If you log off,
the CircumReality World Simulator will be closed, and the world will
stop functioning... until you log back on and re-run it.
Share with your friends: | 
