02 October 2011

OSL (King of Dragon Pass scripting)

Several people asked about the scripting language used in King of Dragon Pass, OSL. This stands for Opal Scripting Language, since “Opal” was the code-name for the game. Apparently we once called it “MiniScript” (but quickly dropped that name).

Our original plans were to use a multimedia development system, mTropolis, and augment it with C++. I’m not sure if scripting was in the original plan, but if not it didn’t take long to add. Scripting languages tend to be much higher-level, are often domain-specific, and intended for use by people who aren’t programmers.

In 1997 we didn’t have a variety of existing languages to plug in. (Today I’d probably use Lua, though others might pick JavaScript or C#.) So we came up with our own. The basic idea was that a relatively non-technical author could create files that were almost valid code. I figured we were going to want to review them anyway, so I didn’t worry too much about syntax errors, or doing things that would be moderately complex.

You can see a sample of scene coding on our site (it’s too large to include here).

The main features were:

We needed to support multiple responses and advice. There are no functions, but there’s simple branching.

A core concept of the game is that most results are not certain. They require an individual to perform a deed. In game terms, this is a test. For example, one of your leaders will test their Combat ability against a dueler. Or the lawspeaker will test his Custom when arguing a case. Or a ring member will test their Poetry (a composite ability) against the surliness of the clan when trying to calm them.

Tests have two outcomes: win or lose. So OSL has those keywords. Sometimes, the degree of success matters, in which case the variable q is set to the amount the victorious side won by.

All variables are global. However, single-letter variables are reset to 0 at the beginning of a scene. Variables are easily accessible to the C++ code, and are actually one of the principal ways that the multimedia code can talk to the other portions.

Variables can contain a floating point value, a string, or refer to a person, clan, or tribe. In the latter case, specific attributes could be used (e.g. otherClan.chief or c.leadership). Variables could also hold lists of values.

We started out with special-purpose functions, often used so that script could handle interaction (such as ChooseSacrifice). But our C++ programmer, Shawn Steele, realized that we could come up with generalized list functions
c = StrongestMilitary(ClansWithPositiveAttitude(NeighboringClans))

All text allowed for placeholders, which would be replaced by a value
response 2: “The <survivorClan.plural> are our neighbors.”
Some of these were context-sensitive, to allow for English grammar (<him/her>). And we had a special placeholder used to vary text (to provide more repeatability).
Bargaining with bandits is <d3:giving chickens to the fox/a sign of how weak we think we are/doomed to fail>

OSL is definitely a “little language” — it’s not Turing-complete. But it serves its purpose pretty well. Robin Laws was able to describe scenes which needed very little cleanup to compile, our QA team was able to read the logic, and it helped glue the mTropolis and C++ code together.


  1. Thanks for those previous answers. I've just got 2 more mechanic questions i really need to figure out, would be amazing if you could help me wrap my mind around the first.

    Every time i've managed to successfully get a candidate of my tribe elected king, the next action phase i'm confronted by the clan chieftains demanding my resignation. Literally the next possible random event that occurs is this scene, they claim i've dishonored the tribe somehow, my advisors agree on this point, yet *not one of them* explains what i had done to bring about this failure/dishonor. It's driving me nuts. I spend lavishly on gifts for the other tribes during the election process (which is fine according to Orlanthi custdom, the others do it as well) and sacrifice to the gods to assist my candidate with his kingship rites, in case that information helps identify my faults at all. Going into the elections, my relations with my tribe mates are all blue (on the relations map, which indicates good relations). I'm really at a loss to see how i can possibly do anything differently.

    If i can't get an answer to it, i'll have to retire the game with full honors. Despite having only owned it for a week or so, it will nonetheless remain of my best gameplay experiences of all time, and if i have to accept that it's just out of my abilities to tackle, i'm totally fine with that. My 5 star review will remain either way without a doubt, and i'll always rave about the game to my friends who appreciate deep strategy experiences.

    Anyways second question is just a simple time limit one, if you spend too long without winning (say the game gets to year 1400, 1450 etc), does the game eventually throw disaster your way you are unlikely to be able to get through?

    Sorry for the length of the post, funny thing is i had the biggest grin on my face after i lost my game. I had put hours and hours into it, and my clan went out fighting my entire tribe since i eventually just said i'll take them all on if i have to (instead of resigning the third or fourth time i got a king elected and they confronted me with the scene i mentioned).

    Thanks in advance


  2. King of Dragon Pass puts a really heavy emphasis on relations. Just because other clans like you as a clan does not mean they think you did a good job assembling a tribe, or that the tribe has been good to them. Remember, they have all made concessions. On a game mechanic sense, a whole set of new relationship values come into play when you are in a tribe.

    Are you trying to become king right off, or letting the notion of a tribe sink in first?

    Oh, and what benefit did you seek when you did the Making of the Storm Tribe heroquest?

    The game never inflicts disaster on you, you need to invite it.

  3. Wow, thanks for the speedy reply!

    My first bid for kingship was in a tribe i created. I used magic to sabotage the first king who was chosen, then managed to get mine elected. I figured the "you've disohonored us all!" seen was because of my sabotage. My tribe fell apart and i joined a different one, one i did not create.

    In the second tribe i waited for a few kings to come and go before making a bid. I spent lavishly on gifts to get my candidate elected, with no funny business this time regarding my opposition. He completed the rites, the celebration lasted for days! Then immediately the "you've dishonored us all!" scene came up again. I resigned as king.

    My third and final attempt was the same as the second, except i said to hell with it i'll fight you all if necessary (my tribe was a powerhouse, i was sure i'd have a good chance at actually defeating them all if it came to it) when the "you've dishonored us all" scene returned as it did the previous two elections, which was right away. About a year later, the tribes made good on their claim to fight me, and i got the scene where their combined forces assault your clan. My clan was a war juggernaught, and i figured if we actually got to pick the options for battle and the game took into account stats of my clan against the weaklings i was up against, i'd have won. I had honed my clan into an unstoppable war machine, we very very rarely lost a battle, and usually completely overwhelmed any and all violent confrontations. I had massive reserves of magic in the bank, most of the war blessings via temples and shrines (i left some out that did not fit with my vision of our clan, for roleplaying purposes), 80 or so elite weaponthanes, battle treasures etc etc. I lost the battle, and promptly lost the game. I figured there was no actual battle calculation, it was like the other apocalypse scenarios where you were just overwhelmed and had no chance. Even still, i lost in spectacular fashion with a grin on my face, my king going down with his crown to rebel scum, refusing to relinquish his throne. It was damn fun. I do not reload games in KoDP ever, i like the idea that my choices are permanent, whatever consequences come. So the game is lost, but i'll try again if i can think of some reason why i kept getting those accusation scenes.

    During the "Orlanth founds the tribe" hero quest, i chose the option that pertains to successfully making a tribe (i forget the exact wording) as the desired blessing. It was very obvious though as the choice to select if you were doing the quest with the intent of tribe-making.

    I just wish they would tell me WHAT the heck i kept doing to immediately bring dishonor, my ring chimed in "yes we have failed them" every time, alright that's all well and good but *how* did i fail, so i can correct the behavior the next time around! Haha so confusing, but i digress, i have no words to describe how great this game is. I see no way to adjust my strategy to succeed at it, but damn it was quite a ride. Easily worth the 10 dollars.

    Oh and a minor note on your response to my second question, so you can play the game essentially forever without it bringing some sort of doomsday event down on you? The manual states that if you don't win, you'll eventually lose, i figured this to mean that if you played for a ridiculous amount of time without winning, Chaos would bring a massive assault on your clan or something to that effect.

  4. Didn’t look in detail, but I’m pretty sure it relates to the nebulous quality called “kingship” — you were probably closer to Bad King Urgrain than Good King Heort on the reputation scale. And as always, it is possible to deal with the situation (though it may be unlikely).

    Do realize that beating clans one on one does not make you an unstoppable war machine! (And if Orlanth and Humakt withhold their blessings, no way will you win. And your weaponthanes know that in their bones.)

    But again, the game calculates odds and gives you a chance.

    I don’t remember the details, but we didn’t design things to drag on forever.

    Anyway, I think the manual covers kingship, though it is a hard quality to pin down.

  5. Much appreciated David, i'll give the other two clan visions i had (one for peaceful, one for balanced) a try, now that i have a better grasp on the mechanics from my war run. I really loved my norse-like warmongers though, we were so rich, so powerful, and had decent relations for such a violence-inclined clan.

    I get the feeling i've finally met my match with this game though. I refuse to go lower than the hardest difficulty, if that means repeated failure, so be it!

  6. I wasn’t going to post again, but it is probably worth playing at Normal difficulty (there is no Easy!). As I think you can tell, the game is very repayable, so you will certainly have the chance to play again at Hard should you so choose.

    At the least, play a Balanced Clan because that makes life a bit easier.

    Hard is really, really, hard. If you truly have more fun with that, go for it, but it will probably prove frustrating, and it is not really the point of the game (which is to be a story). In fact, I just realized I probably should have ripped out the difficulty setting altogether.

  7. Haha i love love love the hardest difficulties in games, i'm masochistic that way. It truly feels like an accomplishment when you finally succeed, you can't get that feeling otherwise.

    Games need difficulty settings, to cater to both the casuals and the hardcore types. I love the fact there's normal and hard difficulty for KoDP (what is the circle inbetween them btw, if there is no easy? Theres 3 options for difficulty, and 2 for game length).

    I was all the way to kingly on the reputation slider during my warlike norse game btw, giving away 150 of my plundered horses skyrocketed it from average to full-on kingly in one year.

  8. Touch Arcade posted their review of September's best iPhone/iPod games, KoDP made the the top of it. Here's what they had to say:

    "I've spent more time playing this game than all the other games that we reviewed in September combined. If my exhaustive review wasn't clear enough, here's all you need to know: If you like simulation games, you needed King of Dragon Pass on your iPhone yesterday. I've still got my fingers crossed for an iPad version, but I'm more than happy managing my clan whenever I've got a few seconds to spare on my iPhone"

    Just wanted to let you developers know in case you missed this, i'm sure you guys love to see feedback and reviews whenever they come out.

  9. You're not going to change or remove the difficulty settings are you? The hard difficulty serves important purposes, it gives the veterans who played the original in 1999 a challenging, and thus rewarding experience. It also gives the more "hardcore" new comers the challenge we seek. Personally, I researched whether or not difficulty settings and sufficient challenge were in the game before I bought it, I likely wouldn't have otherwise (even great games are no fun to some people if they are too easy). I'm sure many others fans who purchase the game enjoy the difficulty slider as well.

  10. I get the feeling ive been cut off from getting answers, which is fine, but PLEASE if you are going to kill the difficulty, let it be known in the update notes so those of us who like the difficulty slider know not to update the app any further

  11. Cut off?

    There’s a difference between “should have” and “will.” It’s hard to imagine removing something from a shipping game, that would break the contract. Bug fixes that remove loopholes, yes.

    The real answer might be to unlock difficulty only after you have played a Normal game. (But, I’m not changing it!)

  12. Yes! Thank you so much

    When I finally become king of dragon pass (long game) on hard, it's gonna be the best moment ive had in gaming, and I've gamed alot in my 23 years! :p

  13. I bought your game on the release day and I'm not excited about this OSL idea. I play 99% of my games on mute. Will this increase the default size of the app ? I have no room left on a 32gb iphone 4 and would hate to have to delete other apps.
    Other then that, I also wanted to add that I love this game! I play a few rounds almost every day.

  14. I'm confused, Dethjem — game size doesn't have anything to do with the scripting language.

    If you somehow meant VoiceOver, you probably thought that meant voice acting, and not accessibility for blind players.

    Now, if we ever do a universal (iPhone + iPad) version, THAT will make the game much larger, because it would mean 2 versions of artwork.