A malignancy grows under the foundations of Caecea Manor. Baron Anton Caecea arranges his marriage with a beloved courtier, Emilia Hall, who he keeps imprisoned in order to breed him a bloodline. He is a practiced Necromancer, and has long stumbled through the primordial secrets hidden within the unnameable tomes he collected. Brought back from their very bones, the newly returned are tortured for horrific lost secrets, blackmail, locations or artifacts until they are once again returned to lie in the Earth. It is from the venerable, rumor shadowed catacombs below that Anton conducts his blasphemous affairs. In a final effort to retain any semblance of hope, Emilia sneaks out a letter addressed to the Church. It is then that the intercepted scroll is passed to the secretive, forbidden department of the Witchfinders. Albert Gray, the leading agent in the office, is a stoic and clinical investigator of the occult who personally adopts the mission to investigate Caecea Manor, to prove the practice of Necromancy, and to put an end to such a blight upon the world. A disquieting narrative weaved through the occult, madness, and despair. You all soon shall be in awe, frozen in the midst of the Shadow of the Ramlord.
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.