Well of Souls Cookies

Synthetic Reality Well of Souls

World Developer Information - Cookies

Using Cookies

For a complete dissertation on the subject of cookies, please see the Lingo Quest Language Dictionary. Specifically the SET command.

The cookies referred to here are neither a bakery product, nor the little notes your browser keeps about your personal activities on the web. These are cookies used in the context of the Synthetic Reality Role Playing Game "Well of Souls" and are used to hold world-specific data on behalf of characters within the game. Any normal programming language would probably call these variables (or objects, if it was bein' high-falutin'), but for some reason the work cookie appealed to me at the time. And with such capricious decisions do programmers become doomed.

Cookies are only available to a running 'scene script' (which was written by the developer of the world you are playing).

The script has limited options of what to do with cookies. Basically they can be written (saved to the character's file on disk) and read (recovered from disk), and some simple comparison and math operations may be performed with them.

Every cookie has a name, and that name usually is defined by the World Developer. If two cookies have the same name, then they aren't two cookies, they are the same cookie. So keep your names straight. For reasons it would take a scientist to explain, you need to 'wrap' the cookie name in a weird syntax to read it, but can just use its name when setting it.

So SAVING a cookie might look like this:

SET myCookie, "Hello, this is the data which goes inside the cookie"

But READING the cookie might look like this:

1: I, the hero, shall now tell you what is in the cookie. it is: #<myCookie>

It's the #< ... > which is the wrapper, and you will eventuallly get a sense for where it is needed. Anyway, it was not my intention to get into the details here. The point of this page is to document the ever-growing list of STOCK COOKIES.

Stock Cookies

For the most part cookies only exist when you SET them. (and only the scene host gets the cookie set), and you shouldn't use a cookie to do the job of a TOKEN. However, there are some cookies which the engine sets for your convenience. These are called STOCK cookies, and you should avoid making cookies of your own with the same name.

Just to repeat the important bit: unlike regular cookies which just hold some data that the World Developer made up. These STOCK cookies give you access to stuff that you might be interested in, and they can NOT be used for general data storage. They hold only what is described here. This list is the only way you know what cookie names are STOCK (i.e. defined by the game and not available to you for general use). If you innocently make a cookie with the same name, you will no doubt be confused when it doesn't seem to hold what you expected.

Most stock cookies are READ-ONLY, meaning that they tell you something you would like to know, and ignore your attempts to stick data into them. But you can write to SOME stock cookies, so pay attention (and hope I document it correctly - I put a W in the column of cookies which can be both read AND written. All cookies can be read, of course!)

Please note that if a cookie has information about a character, it is always about the HOST of the scene (only the host executes the script code)

Here is a summary of all available stock cookies:

HOST COOKIES			Information about host character of scene
#<lastAsk>		W	Response to last ASK command, if any.
#<KM.alignment>			# of monsters killed (with that alignment)
#<num.hostClass>		W	Class # (1-N) of scene host.
#<num.hostLevel>			Level # of scene host
#<num.hostX>			Horizontal position (0-100) of scene host
#<num.hostY>			Vertical position (0-100) of scene host
#<num.hostAge>			age, in minutes, of scene host character
#<num.hostAttack>			aggregate attack points of host
#<num.hostDefense>			aggregate defense points of host
#<num.hostTotalAge>			age, in minutes, of scene host player
#<num.hostHP>			Scene host's Hit Points
#<num.hostMP>			Scene host's Magic Points
#<num.hostMaxHP>			Scene host's Maximum Hit Points
#<num.hostMaxMP>			Scene host's Maximum Magic Points
#<num.hostSTR>			Scene host's STRength (0-255)
#<num.hostWIS>			Scene host's WISdom (0-255)
#<num.hostSTA>			Scene host's STAmina (0-255)
#<num.hostAGI>			Scene host's AGIlity (0-255)
#<num.hostDEX>			Scene host's DEXterity (0-255)
#<num.hostHandSkillN>			(N = 0-7) skill level (0-9) of hand.
#<num.hostElementSkillN>			(N = 0-7) skill level (0-9) of element.
#<num.hostGP>			# of Gold Pieces in host's pocket.
#<num.hostPP>			# of host's unspent PP points.
#<num.hostTNL>			# XP needed for next level.
#<num.hostHaloPoints>			# of halo points (divide by 1000 for #halos).
#<num.hostPKs>			# of Player's killed by host
#<num.hostDeaths>			# of times host has been killed
#<num.hostKills>			# of monsters killed by host
#<num.hostRating>			Numeric PK 'rating' of host..
#<num.hostHuntSkill>			Hunting Skill level (0-?)
#<num.itemNNN>			NNN= item ID number. Returns # possessed by host.
#<num.hostBravery>			Bravery value for host (bigger means braver)
#<num.hostAggressiveness>			Aggressiveness value for host
#<num.hostHandPPN>			(N = 0-7) appx PP spent on training hand.
#<num.hostElementPPN>			(N = 0-7) appx PP spent on training element.
#<num.hostXP>			Scene host's curent XP (appx)
#<num.hostMaxXP>			Scene host's highest XP ever (appx)
#<num.hostTotalXP>			Scene host's total XP ever earned (appx)
#<num.hostBirthDay>			Day of month scene host's character was created
#<num.hostBirthMonth>			Month of yearscene host's character was created
#<num.hostBirthYear>			Year that scene host's character was created
#<num.hostHandRatio>			Numeric ratio for hand
#<num.hostMagicRatio>			Numeric Ratio for Magic
#<num.hostEquipIdNN>			id of equipped item in slot NN
#<num.hostTotalPP>			total PP earned by host over lifetime of character

HOST PET COOKIES			Information about the host's pets.
#<num.hostPets>			# pets owned by host.
#<num.hostPetLevel>			level of highest level pet.
#<num.hostPetId>			monster id of the pet the host has 'in scene' (or 0 if none)
#<num.hostHasPetNNN>			Returns how many pets of id=NNN are owned by the host.

SERVERCOOKIES			Information about the MIX server
#<num.serverTimeHour>			LocalTime Hour of day (0-23) for host
#<num.serverTimeMinute>			LocalTime Minute of hour (0-59) for host
#<num.serverTimeMonth>			LocalTime Month of year (1-12) for host
#<num.serverTimeDay>			LocalTime Day of Month (1-31) for host
#<num.serverTimeYear>			LocalTime Year (e.g. 2001) for host
#<num.serverTimeDoW>			LocalTime Day of Week (1-7) (1=Sun)
#<num.serverTimeNow>			Seconds since 1970 or so
#<str.serverName>			Name of the server host is on.

SERVERRULE COOKIES			Information about the MIX server 'rules' (return whatever rule is set to)
#<num.ruleMaxPlayers>
#<num.ruleMaxAFK>
#<num.ruleMinVersion>
#<num.ruleLadder>
#<num.ruleNoCheat>
#<num.ruleNoMod>
#<num.ruleNoMigrate>
#<num.ruleNoPK>
#<num.ruleAllPK>
#<num.ruleNoBleep>
#<num.ruleNoEavesdrop>
#<num.ruleNoPets>
#<num.ruleArenaPK>

TIME COOKIES			Information about local (client) time in game
#<num.timeHour>			LocalTime Hour of day (0-23) for host
#<num.timeMinute>			LocalTime Minute of hour (0-59) for host
#<num.timeMonth>			LocalTime Month of year (1-12) for host
#<num.timeDay>			LocalTime Day of Month (1-31) for host
#<num.timeYear>			LocalTime Year (e.g. 2001) for host
#<num.timeDoW>			LocalTime Day of Week (1-7) (1=Sun)
#<num.countDown>			Seconds left on COUNTDOWN timer.
#<num.timeNow>			Seconds since 1970 or so

GENDER COOKIES			Information about scene host's gender
#<g.num>		W	The host character's gender number: 0,1,2, or 3
#<g.xxx>			Replaced by 'xxx' entry of gender.ini file
#<str.uniform>			Host's current uniform, if any
#<str.name>			Host's name
#<str.soul>			Host's Soul ID ("Soul 1234" or "2B3C3E4F")

TOSS COOKIES (sorry)			set when @eventActorGiveN event triggered
#<item.id>			set to ID of item tossed to actor, or 0 if gold was tossed.
#<item.goldGiven>			set to #GP given, or 0 if item was tossed.

ITEM COOKIES			get information about current item
#<item.id>		W	set ID of item to get info about
#<item.name>			its name
#<item.class>			its class number
#<item.price>			its price (in store)
#<item.level>			its level
#<item.element>			its element number
#<item.attack>			its A points
#<item.defense>			its D points
#<item.hp>			hp it gives when consumed
#<item.mp>			mp it gives when consumed
#<item.desc>			long desciption of item
#<item.ap>			ability points provided by item
#<item.fp>			"find probaility" of item (chance of loot)

MONSTER COOKIES			get information about current monster
#<monster.id>		W	set ID# of monster to get info about
#<monster.name>			its name
#<monster.dex>			its dexterity
#<monster.agi>			its agility
#<monster.sta>			its stamina
#<monster.str>			its strength
#<monster.wis>			its wisdom
#<monster.level>			its level
#<monster.element>			its element
#<monster.mp>			its max Magic Points (I probably did monster.hp too)
#<monster.attack>			its A points
#<monster.defense>			its D points
#<monster.expPts>			Experience Points earned for killing one
#<monster.gold>			Gold earned for killing one (base amount)
#<monster.alignment>			its alignment
#<monster.skin>			its skin name
#<monster.lastFightCount>			Number of monsters which took part in last fight.
#<monster.lastFightIdN>			the id of the Nth monster that took part in last fight
#<monster.hp>			its hit points

SCENE COOKIES			get information about current scene
#<scene.id>			ID number of scene (read-only)
#<scene.bkgnd>			name of background jpeg for scene
#<scene.fx>			current scene FX number
#<scene.weather>			current scene weather number
#<num.isPKAttack>			0 - no, 1 - yes (valid in CAMP scene only)
#<num.closestLink>			link # of closest link on map (at scene start)
#<num.closestLinkStyle>			CampStyle number (from link editor) for closest link on map
#<str.mapName>			string name of current map
#<num.mapNum>			+MAPS table ID of current map
#<num.mapFlags>			+MAPS table mapFlags of current map
#<num.peopleInScene>			# players in scene
#<num.peopleInParty>			# players in scene who belong to host's party
#<str.actorNameNN>			returns name of actor NN in scene

SPELL COOKIES			get information about current spell
#<spell.id>	W		Set ID # of Spell to get info about
#<spell.name>			name spell
#<spell.pp>			pp required to purchase spell
#<spell.element>			its element number
#<spell.damage>			damage from spells.txt table
#<spell.price>			MP required to cast it
#<spell.level>			element level (minLevel from spells.txt)

TROPHY COOKIES			get/set information about host's trophy bag
#<num.TrophyBagOpen>	W		0 if bag closed, 1 if open (cannot open 0 - slot bag)
#<num.TrophyBagWidth>	W		width of bag
#<num.TrophyBagHeight>	W		height of bag
#<num.TrophyBagSlots>			num.TrophyBagSlots
#<num.TrophyBagSlotsInUse>	W		non-empty slots in bag (WRITING any value, empties bag completely)
#<num.TrophyBagEmptySlots>			empty slots in bag
#<num.TrophyNNN>			how many trophyId=NNN hero has, in total, in bag
#<num.TrophyBagRoomNNN>			how many MORE trophyId=NNN hero could take (filling all stacks and slots)
#<num.TrophyIdInSlotNNN>	W		id (or 0) of trophy in slot NNN. (write REPLACEs slot with a SINGLE trophy)
#<num.TrophyCountInSlotNNN>	W		qty (or 0) of trophy in slot NNN. (write REPLACEs count, without changing id)

MISCELLANEOUS COOKIES			Whatever
#<num.wosVersion>			returns DECIMAL value of HEX version. A90 returns 2704
#<num.hostCookieFaults>			estimated # of times host has 'hacked' his cookies. Only if config.ini has cookieProtection turned on.
#<str.worldName>			Name of world currently being played.
#<event.missionId>			id associated with @eventMission event

HOLIDAY COOKIES			The game will detect certain world holidays for you
#<num.holidayId>			returns 0 if today is not a holiday, otherwise the holiday id.
#<str.holidayName>			Name of holiday "Christmas"
#<str.holidayGreeting>			Greeting for holiday "Merry Christmas"

WORLD TABLE COOKIES			These let you access world table data
#<num.DevTableId>	W		Selects which of your tables (00-99) to be used (DevTableNN.txt)
#<str.DevTableRowId>	W		Selects which ROW of the current table is to be used
#<str.DevTableCOLNN>	R		Returns the value from column NN of selected row

Cookie Pointers

To implement arrays and other fun things, you need a cookie which "points to" another cookie. You can achieve this goal via the asterisk (*) character.

If:

#<cookieName>

gives you the contents of the cookie called cookieName, then:

*#<cookieName>

gives you the contentes of the cookie whose name is inside the cookie called cookieName.

More concretely:

SET dataCookie, "Bill"
SET labelCookie, "dataCookie"
1: hello, my name is *#<labelCookie>

I hope that made sense. I wrote it down better somewhere else, but for some reason I can't seem to find it. If you ever see any documentation that says to use @ instead of *, then let me know. It was a mistake to use @ (in A70) and I changed it to * for A71.

Camp Styles

Your world may need to do a lot of scripting in the standard camp or fight scenes, based upon which map the player is on. You can do this by testing against all your map numbers or link numbers, but that quickly becomes tedious.

As of version A74, each link may have a 'camp style' number assigned to it (you do this with the LINK EDITOR... it's just a number, and the game makes no use of the number. It's up to YOU, master scene designer, to make it useful)

For example, your world may have 2 major sorts of terrain... dry and wet, or light and dark, or good and evil... You might assign camp style '1' to mean one, and '2' to mean the other (and if you have more sorts, use more numbers).

Then, using the link editor, you assign a style value to each of your links.

Then, in the scene code for the standard camp scene (for example), you simply test one cookie (#<num.closestLinkStyle) and use its value to determine anything special you do for ALL 'good' scenes or 'bad' scenes. Setting the background, weather, etc.

To some degree this is redundant to the pre-existing values in the link editor, but this one is general purpose and can mean what YOU want it to mean.

Last Fight Monster Info

You may want to do something special in your script depending on what monsters were just fought. There are two cookies to let you check that out.

The first one (monster.lastFightCount) tells you how many monster took part in the fight. This does not includ heroes (no matter whose side they were on) or pets (ditto), nor does it include any friendly monsters (For example when you use the FIGHT command and have a negative value for the monster id to make it fight on the side of the heroes). It's just the number of bad monsters that got added to the scene over the course of the fight. It gets cleared to 0 at the start of the next scene (even if it isn't a fight), so you can only take advantage of this cookie while still in the fight scene itself

The second one (monster.lastFightIdNN) is actually an array of cookies. Instead of typing 'N' you need a number between 1 and the lastFightCount (so if lastFightCount says there were 4 monsters, then use 1, 2, 3, and 4 to check out data about the individual monsters.

Please note that you can only see general info about the monsters and not specifically whether they got killed, who killed them, etc. This is good for handing out special rewards for killing particular sorts of monsters.

Here is a possibly silly example...

; start a fight with monsters from the map
FIGHT *
; now check what we killed
IF DEAD @youLostFight
SET index, 1
SET numMonsters, #<monster.lastFightCount>

@loop

COMPARE #<index>, #<numMonsters>
IF> @allDone
; This is the tricky bit, we need to add 'N' to the end of the cookie name
SET lookup, monster.lastFightId#<index>
ADD index, 1
; the cookie 'lookup' should now have 'monster.lastFightIdN' in it where N is 1, 2, 3, etc
; now we need the content of that cookie, so we use it as a cookie pointer..
SET monster.id, *#<lookup>
; OK, now we can fetch info about this particular monster via the normal monster cookies
1: You encountered a #<monster.name> which was of level #<monster.level>
COMPARE #<monster.level>, 12
IF< @loop
; this monster was level 12 or higher, let's give them something special, but only 50% of the time
IF R50, @loop
; So, they are powerful AND lucky
1: Here, take this fine %I50, whatever that is!
GIVE I50
GOTO @loop

@youLostFight

1: you got killed, so while I *could* tell you what you just fought, I don't think I will bother.

@allDone

END

Holidays

You might want to do something special on a special holiday. You can do the math yourself, of course, but the holiday cookies will help you detect certain world holidays.

#<num.holidayId> will return one of these values (the number), including '0' for 'today is not a holiday I recognize'

0	None
1	Birthday
2	Easter
3	Thanksgiving (USA)
4	Christmas Eve
5	Christmas Day
6	Boxing Day
7	New Year's Eve
8	New Year's Day
9	Groundhog Day
10	Valentine's Day
11	St Patrick's Day
12	April Fool's Day
13	Earth Day
14	Cinco de Mayo
15	Mother's Day
16	Memorial Day
17	Father's Day
18	Canada Day
19	July 4th
20	Labor Day
21	Columbus Day
22	Halloween
23	Veteran's Day (USA)

Sorry for the USA Bias, but what can I say? Also, the BIRTHDAY is of your WoS character, not you personally.

Developer Tables

So, say your world has need for a lot of tabular data.. stuff that the WoS engine doesn't need to know about directly, but that you use in your scripts a lot. Say you have your own skill system, or potion making formulas or anything else which can be defined by rows of columns of data in a table.

First the limitations. No more than 100 tables (stored in your world folder in files called "DevTableNN.txt" where NN is 00-99)

No real limit on the number of rows in a table (one line of text in your file is a row), but smaller is faster.

each row is a bunch of comma-separated values (just like a QUEST file, only YOU decide what the columns mean.) You are limited to 30 columns and each row of text must be less that 4000 characters wide.

You can pepper your table with comments, where anything on the line after a 'semicolon' is ignored.

Each column can have an arbitrary string (max length of 100 characters per string, I think.. well, same as for QUEST whatever that is MAX_PATH in computer terms.. minus a couple). It can be a number or text, but you should put text inside double-quotes (ESPECIALLY if the string contains a space or a comma).

You can NOT use #include in a DevTable.

You do NOT put QUEST commands in a DevTable.

The first argument on each line is its "RowId" and should be unique. It can be a number (like I do with spells and such) or some text if you like. But each row needs a unique id (unique within that one table file). When you ask me to look for a row by its id, I am going to start with the first line of the file and keep looking until I find it or the end of the file.

Remember, WoS will do nothing with your devTables other than fetch values from them (via cookies). And these are read-only, like the quest files. (Developer can edit them, just like quest files, but for the end player they do not change.)

They are included in the world version, so tampering will result in a 'modified world'

Example Table: DevTable32.txt in your world folder contains:

; This is my table of skins used in my mini-game
; ROWID,  COL1=Actor#, COL2=SkinName
Butter, 1, "Jumping Butter Can"
Cheese, 2, "BlueCheese"
; Note, dan doesn't read these comments
; so that stuff I said about COL1 is just for me

Then, to read the table in my SCENE script, I need to do three things:

; 1.) select the current DevTable
SET num.DevTableId, 32
; 2.) select the current ROW of the table
SET str.DevTableRowId, "Butter"
; 3.) fetch one of the COLUMNS of information
1: the skin name is #<str.DevTableCOL2>