Html5 — 06 — ExcaliburJS Critique
Hello! I am Samuel Asher Rivello, a professional game developer with over 20 years of game development experience. This series aims to share my learning journey with HTML5 gaming.
ExcaliburJS is a robust HTML5 game engine written in TypeScript, designed to make 2D game development more accessible and efficient. It provides a rich set of features that simplify the creation of interactive and visually engaging games.
By leveraging TypeScript, ExcaliburJS ensures type safety and improved code quality, which can significantly enhance the development experience. Previously, I provided a basic overview.
> See My ExcaliburJS Overview Article
Critique
Overall, I have very positive impressions so far!
ExcaliburJS has clearly been created with a deep love for games and an extensive knowledge regarding game development.
While ExcaliburJS has many strengths, there are areas for improvement too. The product is still pre-1.0 (as of June 2024). This is a great opportunity to make some changes for the benefit of current and future users.
Below, I’d like to talk about things that are present in the current offering of ExcaliburJS and give thoughts on the API design and naming.
API Hierarchy Critique
Some high-level objects, including ex.Engine have a flat API with many sibling-members of diverse areas of interest.
Current
// Partial list of members
// (Member signature omitted for brevity)
const engine : Engine = new Engine();
engine.addScene;
engine.displayMode
engine.browser;
engine.timescale;Suggested
I suggest instead to maintain an api with tidy boundaries including a lean hierarchy of subobjects. This makes an API clearer and easier to navigate. By grouping related members into distinct areas like Scene, Time, Screen, Statistics, Physics, Environment, and Input, developers can more quickly locate and understand the functionality available in the Engine class. This KISS approach can apply to the rest of the API too, not just Engine.
// Partial list of members
// (Member signature omitted for brevity)
const engine : Engine = new Engine();
engine.scene.addScene ();
engine.screen.displayMode;
engine.environment.browser;
engine.physics.bodies;
engine.time.timeScale;API Consistency Critique
Many locations of the API suffer from inconsistent naming where one system uses one approach and other systems differ. Some areas treat only new words with TypeScript’s typical camelCase, sometimes not. Many locations offer redundancy to get/set values with sometimes unclear lifecycles. This exists throughout the codebase.
Current
engine.screen.goFullScreen(); // Setter
engine.screen.exitFullScreen(); // Setter
let b = engine.screen.isFullScreen; // Getter
let b = engine.isFullscreen; // GetterSuggested
Best practices suggest to have just one setter/getter boolean with predictable lifecycle for readability, intelligibility, and simplicity.
engine.isFullscreen = true; // Setter
let b = engine.isFullscreen; // GetterAPI Abbreviation Critique
There are many classic arguments against abbreviations in code. A primary one in favorite of abbreviations is to ‘type less letters’. As with programming in general, fingers hitting the keys is among the least significant portions of the job, and thus should not be prioritized.
Current
Throughout ExcaliburJS there are abbreviations used and used inconsistently. A partial list is shown here with suggestions added.
Suggested
API Naming Critique (Compounds)
Much of naming conventions comes to personal taste. Given that alphabetic order is used through many programming-adjacent systems (e.g. documentation, intellisense), I prioritize exploiting alphabetic ordering when naming compound members made up of 2 or more words.
Current
While inconsistently applied, I see much of the existing API use adjective-noun ordering for members. This is indeed more grammatically familiar for English speakers.
const particleEmitter = new ex.ParticleEmitter({});
particleEmitter.minAngle = 0;
particleEmitter.maxAngle = Math.PI;Suggested
I recommend noun-active naming for members. This comes with higher navigability (e.g. documentation and intellisense).
const particleEmitter = new ex.ParticleEmitter({});
particleEmitter.angleMinimum = 0;
particleEmitter.angleMaximum = Math.PI;API Naming Critique (Booleans)
Its a common practice to give specific naming to specific variable types to help intelligibility. One application of this is naming booleans.
Current
Throughout ExcaliburJS the naming is applied inconsistently. A partial list is shown here with suggestions added.
Suggested
I suggest that the API consistently prefix boolean variable names with “is” or “can” for most cases and where grammatically helpful with “are”, “has”, “can”, or “will”.
Conclusion
In conclusion, ExcaliburJS is a powerful HTML5 game engine that offers a rich set of features and a robust API for 2D game development. While there are some areas for improvement, I’m excited about the product.
Resources
🦜 Contact
- Samuel Asher Rivello has over 20 years of game dev XP. He is available for remote, contract hire as a game developer and game dev educator.
- Contact Sam today to say hi and discuss your projects!
📜 Articles
- Html5–01 — Gaming Overview
- Html5–02 — PixiJS For Gaming
- Html5–03 — PixiJS Project Template
- Html5–04 — Unit Testing For PixiJS Games
- Html5–05 — ExcaliburJS Overview
- Html5–06 — ExcaliburJS Critique
- Html5–07 — ExcaliburJS Project Template
