The Shadow of the Ramlord
It is the 18th Century, at the height of the Holy Roman Empire's power. In a small, nondescript region of Europe lies Caecea Manor, the seat of one of the more influential houses in power led by Count Anton Caecea. Rumors among the villagers, spreading far enough through the country to pique the interest of the Church, is that the Manor is the centerpiece of Occultist and Necromantic activity. Not able to stand idly by, the Church ordains the intervention of their leading Witchfinder in the region, Albert Gray, to investigate these claims. He follows the trail of an arranged marriage between the Count and a beloved Baroness, Emilia Hall, right to the manor itself.
An insidious narrative through the occult weaves itself from her pained diary entries, the lost secrets beneath the manor, and the confessions of the once dead. The extent of the depravity, and the depths plunged by the singularly corrupt Count, is beyond even the wildest speculations. The region is consumed by... The Shadow of the Ramlord.
Dark Craft Studios
Glenn Winkelmann Jr - Head Project Lead, Developer, Writer, Level Designer
Ian Wiese - Lead Writer
Spelos - Lead Programmer
Karba - Lead Level Designer
Jarod D'Camp - Lead Composer
David Bodtcher - Voice Acting Count Anton Caecea
Vacant - Voice Acting Albert Gray
Vacant - Voice Acting Countess Emilia Hall
I'm Spelos, and I'm the lead programmer of The Shadow of the Ramlord. In this development diary, I would like to talk about how we structure and organize our code, as well as keep it consistent throughout our codebase. While this article delves into the technicalities of programming, it also provides a few tips and suggestions to other developers or hobby mod creators. So let's get into it.
Amnesia's scripting language is very tightly coupled with Amnesia's API. That, unfortunately, means that a lot of proven methods of writing clean code do not apply. That is why I decided to write a derivative standard that tries to implement as many clean code principles as possible while keeping script files light and easy to read. The standard is public and you can find it HERE. This public standard goes into details of both styling and form of script files and proposes one of many possible structures.
Programmers read their code much more than they write it. Amnesia mod developers read Script_Functions part of the wiki much more than they read their code. Why is that?
It is because Amnesia modders have to interact with the API that Frictional Games designed. Your script is a plugin for Amnesia. That's why all of the code is dependant on Amnesia's internal signatures. Is Amnesia's API well written? Absolutely not. Can we work around it? Yes, we can.
A good example of the type of enhancement that we do to improve code readability is long function signature commenting. Take for example this extended function for creation of a particle system.
CreateParticleSystemAtEntityExt("BlueDust", "DustCloud.ps", "DustArea", false, 0.3f, 0.9f, 0.3f, 1.0f, true, 1.0f, 0.5f, 5.0f, 6.0f);
Granted, this is an extreme example, but it demonstrates the problem in a nice way. You see that 'false' boolean that's the fourth parameter? What does it do? And how does it differ from the ninth 'true' boolean? What are the floats on about?
Chances are, you would consult the all-knowing FictionalGames Wiki. What happens to a programmer when she needs to consult documentation in the middle of an algorithm? She loses flow, gets distracted, annoyed even.
We cannot completely get rid of this problem without abstracting the whole API, which is not an option given you cannot easily include other scripts inside your own and copying a few hundred lines into each of your script files isn't a good solution. And so we solved this potential issue by forcing an 80 character limit on a line and parameter comments for functions with long signatures. I mean, look for yourself, doesn't this look better?
You can now confidently say what those booleans do. And while some people would swear with their life that they remember all these parameters, since they're expert modders, I would argue that readability has more advantages.
Look at the color parameters. What color is it closest to? Green, yes. Now tell me, why is a "BlueDust" particle green? It is a bug, yes. Would you ever notice in the previous example? Most likely in the game when you see that the dust is green. Then you would go into the code look at the large function and... Well, you'd probably check the wiki to see what those parameters do. But in the readable version, you take a look at the color, go "Yep" and fix it within a few seconds.
There is a ton of small little improvements you can do to ease your development and save yourself from dealing with terrible issues. Most of these are not even specific to AngelScript. I would highly recommend a book by Dustin Boswell and Trevor Foucher called "The Art of Readable Code". There is a free online version. It includes a lot more great tips for improving your programming and making it more human-friendly.
After all, programming with other people is the best way to improve, have fun, and make something awesome together.
No articles were found matching the criteria specified. We suggest you try the article list with no filter applied, to browse all available. Post article and help us achieve our mission of showcasing the best content from all developers. Join now to share your own content, we welcome creators and consumers alike and look forward to your comments.