Erik Hazzard

Crafting Experiences with Data Visualization

Thu, 26 Feb 2015 00:00:00 GMT

My presentation about design, data visualization, and user experience at a D3 meetup Story-Telling, Design, and Data Visualization I recently gave a presentation at the Oakland D3 meetup, organized by the amazing @seemantk. The presentation is about an hour long, so I wanted to summarize some of the topics I discussed. This post is an overview of the talk, along with some notes. You can watch the presentation here (or the video above). User-Driven Experiences This sounds so nebulous: 'User-Driven Experiences.' It's as seemingly meaningless as 'synergy,' but in my mind it is a clear philosophy. I'm a developer, and I sometimes get so wrapped up in thinking about code that it's hard to step back and see the purpose that code serves. We write code to create a product, which is (at least in my line of work) consumed by people. Since people use our products, we can do well to place the person's experience at the forefront of our design and development processes. What do I mean? Every decision we make - color, font, data visualization type - should be carefully thought about in terms of how it will impact the user's experience. First, decide what kind of experience you want the user to have. Then, pick the visualization type that best will deliver that experience. If you're already set on using a cool force layout visualization, you may miss the larger picture if that visualization type isn't the most effective for the story you're trying to tell. Analyzing Experiences with Interest Curves Maybe a user-first approach still sounds abstract. So, in an attempt to make it more clear, let's analyze what an experience looks like. As with any kind of data, there are an infinite number of ways to visualize an experience. We could look at an experience in terms of flow, which can be very helpful when designing games. We'll save flow for another talk, and focus instead on Interest Curves. Interest Curve - Interest over Time One way to visualize an experience is to think of it in terms of interest over time. This is just a tool - the above curve isn't some universally perfect example of a good experience - but it's pretty damn good. Most successful books, movies, and games follow this general shape. A great experience often starts with a hook. Sometimes it's cheap, like an explosion or a character death. But whatever method is used, the goal of a hook is to pique your interest. Then, we need to let that interesting experience sink in, to allow the peaks of interest to be meaningful. It eventually culminates in a climax, which is ideally the peak of the entire experience. This can be applied to any kind of experience - not just a game or movie - but also physical experiences. Interest Curve in Real Life This applies equally to data visualization. While a bar chart may not represent a temporal dimension, users experience your visualization over time. People must process what the data visualization is trying to tell them, and if you just throw all the data at them it's a bad experience. If you can instead craft the experience to have peaks and valley of interest, it could be more powerful. Loading Bars We often overlook one of the strongest parts of the experience - the initial loading experience. This is our hook. If we can ease the user into an experience, or give them a taste of what it will be like, we can help craft these peaks and valley of interest. I talked a little bit about this a previous blog post on misleading users, and you can jump to the discussion on loading bars in my presentation SVG Filters We can't talk about chart junk without talking about filters. Tufte is right in saying that chart junk obscures the data:ink ratio; but how important is a high data:ink ratio is people have a bad experience? What's better: a forgettable visualization (i.e., story) with a perfect data:ink ratio; or a memorable story which creates interest and sparks discussion that uses decorations and chart junk? Depending on your audience, the answer is almost always the latter. If you're designing for scientists or white papers, decorations make the audience unhappy. But, if you're designing for the general public, sometimes decorations can create a more compelling experience. Maybe it's not a 'pure data viz,' but is that truly the end goal? SVG Filters are a tool that can be used to create 'chart junk,' or to also craft a more compelling experience. You can check out some of my thoughts on filters: enhancing data visualization with SVG filters and using SVG filters to create a fog of war effect, or jump to the discussion of the power of filters in my presentation. Games Game designers grapple with unique design problems. They have to somehow integrate audio design, animation, UI design, gameplay, art, storytelling, and numerous other disciplines together. Games have the highest ceiling of difficultly in terms of experience crafting. A successful game must be successful in creating experiences using numerous art forms, then bring all those individual experiences together to craft a larger, more coherent experience in a player's mind. If we view design as a search problem, then games can provide a wealth of inspiration. I talk about data visualization in games, and you can also jump to the discussion on games in the presentation. Data Visualization Driven Game Design I'm currently working on a game which focuses on data visualization help improve your gameplay experience. More information can be found in a previous post, or you can watch a demo of it. End Feel free to check out the presentation, which goes into more depth for each of these concepts. Slides of the presentation can be found on github.

Data Visualization in Games: Leaderboards

Wed, 24 Sep 2014 00:00:00 GMT

In one of my earlier gaming memories, I'm playing Centipede on an old, busted arcade cabinet. Not at an arcade though, but at a doctor's office. I guess it's a bit strange now to think that a doctor's office had a small arcade in it, but at the time it made sense. I remember visiting that particular doctor's office a few times and caring only to play that game. The memory of actually playing the game is faded now. But even as I write this over two decades later, the anticipation I felt before playing it is just as palpable. Even today, few games can elicit such excitement as going to the doctor's office did. The game itself was irrelevant. In fact, the game probably wasn't Centipede. What stuck with me, what caused my Christmas-eve-night eagerness for the next opportunity to visit the Doctor's office, was a leaderboard. Leaderboards can create powerful emotional responses. As for my six-ish year old self, they can create motivation to play a game - regardless of the game. I wanted so bad to play not because the game was fun (it probably was, but I can't even remember the game). I wanted so bad to play because I wanted to see my three initials in that high score screen. I was excited to return because I hoped my name would stay on that list, even they probably unplugged it often and the high scores likely got wiped (but I didn't understood that). Leaderboards provide far more than just motivation. Not all players care to see their name on a global leaderboard, but competition is only one facet. Data Visualization with Leaderboards Leaderboards are a visualization of achievement. Their goal is to make comparisons between some player (or item's) ranks. This is a broad statement because implementations of leaderboards can be found not just in arcades, not just in single or multiplayer games, but also in non-games. Reddit.com is a great example of a leaderboard in a non-game context (in other words, gamification). Each post is upvoted, or downvoted into oblivion, and each vote will cause its position on the 'leaderboad' (i.e,. the site) to change. Reddit is a social leaderboard for content. Even if you never post something yourself, you can still affect a post's position. Reddit is the social leaderboard for content on the internet By visualizing data, you give data power. The method of visualizing it shapes how people interpret it and their emotional responses. I'll focus specifically on games, but all the same concepts apply in non-game (i.e., gamification) context. I want to discuss leaderboards from two perspectives: How leaderboards can be visualized and their effect on players. Leaderboard Effects Leaderboards serve many purposes, but three powerful ones are:

Measuring Progress / Achievement: Leaderboards provides a way to visualize your skill progression. As you become a better player, you get higher scores, and you're able to compare it with past performances.
Status: Many players are motivated to keep playing and improving because seeing your name on a leaderboard provides status. Most players feel pretty good when they see they're better than a bunch of other players.
Providing a sense of what's possible: In a global, absolute leaderboard, the highest score gives you a sense of what's possible. If you know the best player has 300,000 points and you're 'stuck' at 200,000, you will know it's at least possible to increase your skill to reach that higher score. The caveat here is that if the leaderboard displays cheaters (like pretty much every iOS game center leaderboard I've seen), you completely lose this benefit - and this goes from being a positive to a negative. If the highest score is outside of the realm of possibility, or *everyone* has it, then it's not a realistic measure of potential skill. How to Visualize Achievement Leaderboards aren't the only way to visualize achievement of course (badges are another popular method), but they are one of the most effective for encouraging engagement. The obvious leaderboard visualization, and a fairly inefficient one in today's games, is the traditional arcade-style high score screen with ten to twenty names listed. For a local arcade cabinet, this can be effective. However, for a persistent, multiplayer game with social components, there are more effective visualizations. Few players will be the top twenty in the world, and not all players are motivated to appear on a global leaderboard. Types of Leaderboards If many people play a game, then of course few people will be in the global top twenty. Many players will even be discouraged because they know they will not (and have no desire) to reach the top tier. For non-local multi-player games, relative leaderboards can be more effective. Relative With relative leaderboards, the leaderboard is centered on you. You can see people above and below you, but the goal isn't necessarily to reach the top. Progress is much easier to see, as you will be able to more easily rise above the people that were ranked higher than you. Geographical Another way to present leaderboard information is to group is by geography. This could be based on region (e.g., US or Europe), or at a smaller state, city, or even local level. Maybe it's not realistic to compete against the world, but you'll probably be able to achieve a higher ranking at a city level than you would at a national level (at least, initially). Local Leaderboards Even if a game is multi-player, it does not necessitate a multi-player leaderboard. A local listing of your own high scores and progress is powerful. Not all players are motivated by the status a public leaderboard provides, but nearly all game players are interested in seeing progress to some degree. Temporal By grouping by time, leaderboards can stay fresh. Maybe you couldn't get to the top twenty last week, but perhaps you can this week. If the rankings are changing by time, it can also make the game feel more active. Dedicated players that show up day after day (or week, or month - whatever the interval is) have high status. For instance, on Reddit users that constantly comment and receives a lot of upvotes will often have more of an impact on the conversations than an unknown user. The flip side - and another advantage - is that with a time based ranking system, more players have more chances to show up in the leaderboard. Ladder Systems Games like Starcraft and League of Legends (and most other skill-based games) have a ladder system. In it, there are various 'tiers', or 'leagues'. Each tier may have numerous divisions (instances of the tier - for example, there may be 1,000 'Bronze League' divisions which each contain 100 players). The lower tiers usually have a ton, while the final tier may have only a single division. You advance to the next tier by ranking high in your current one. This is a sort of hybrid of a relative and absolute leaderboard. Absolute, in the sense that you may be number 99 out of 100 - but relative in the sense that you're in a 'group' and not compared absolutely to the top tier of players (unless, of course, you're in the top tier). Ladders systems provide a way for players to increase their position in a leaderboard, but do so at a rate that is neither too fast or slow. If you're good, then you'll quickly get to a point where you stop progressing quickly - and if you're bad, you'll drop down in ranks and get to a point where you can rise up by increasing your skill. More Leaderboards These aren't the only types of leaderboards. The type that produces perhaps the most motivation are leaderboards that pit groups against each other. For example, teams (or guilds, or clans, or groups in a real world company) that have a ranking. The members of each team want their team to be at the top, and often can be more motivated to be engaged vs. their non-teammed, solo counterparts. Other types in your social graph, how you and your friends compare to each other. There is really a virtually limitless way to slice and categorize the data. Each slicing, each way you present a leaderboard, will change not just how the player perceives their achievements and progress; but will also affect their motivation. By showing friend comparisons, for instance, there is social proof which can be stronger than competing against anonymous players. However, some players are more motivated to improve their own skill and may find local leaderboards that track their individual progress more effective. When you start combining different types of leaderboards, you can create powerful incentives for playing (e.g., grouping by time and location). Allowing sorting can provide another powerful way of exploring the data. Providing too many options, too many leaderboards, is probably a bad idea. However, being cognizant of your game's goals and understanding your game's audience and their goals, providing different types of leaderboards can create incredibly strong impulses to play. In the case of my younger self, the presentation of achivements through leaderboards can be even more powerful than the game itself.

Designing a Browser Based Game with D3.js

Sun, 21 Sep 2014 00:00:00 GMT

Scars of the Untrodden, an HTML5 game built using D3.js. View the introduction First impressions are powerful. The initial exposure to a game, book, or even web application, affects your not only your interest in it, but your perception and expectations of it. That initial exposure is a promise to the player, reader, or user. It's a sort of taste of the full experience, a sort of summary. If you read a book that starts out like Harry Potter but halfway through turns into Game of Thrones, the author did a bad job at getting across the books' tone on the first page. Scars of the Untrodden is a browser based, fantasy, rouge-like map exploration game I've been working on which makes heavy use of data visualizations. I waited until I had completed most of the game to work on the introduction. I feel the initial experience is incredibly important - not just from an aesthetic perspective, but from a teaching one. Within the first moments of gameplay, I feel that a good game will communicate the tone of the game, teach the user what kind of experiences to expect, and convey a sort of summary of the full experience. One of my favorite examples of a game executing this beautifully is Megaman X ( watch Sequilitis's explanation of Megaman's level design - warning: explicit). In this post, I'd like to share part of the initial experience of my browser based HTML5 rogue-like fantasy game. The core of it uses SVG (and D3.js) for gameplay, but there is also a heavy emphasis of data visualization in the game. It's a work in progress, and I'm not a designer, so I welcome suggestions and criticisms. I'll describe the things I'm trying to accomplish from a design standpoint, as well as how I'm accomplishing them from a development standpoint. Feel free to take a look at the initial experience, which is what I'll be discussing in this article. NOTE: This is designed for modern browsers, and may not work in older browsers and some mobile devices Sources of Inspiration No idea is developed in a vacuum. Taking ideas from other disciplines can be powerful and create a richer, more unique game experience. Ideas from game design can be applied to other fields as well - for instance, I tried to incorporate some of the concepts from Sequelitis's Megaman Video into our Five Labs experiment. These are the goals I'm trying to accomplish with the initial experience of my game:

Use diegetic elements as much as possible, and establish a clear and consistent design language.

Create a promise (summary) of the full gameplay experience: convey the tone and communicate the large role data visualization will play. This is a broad goal, and also involves things such as immediately providing the player with meaningful choices There are countless sources of inspiration I've used, but I want to focus on just a few. Deadspace Deadspace not only has amazing diegetic design, but it also has a clear design language. Interactive elements have a consistent color, and your character is in a consistent position (your character's healthbar is on your character, so a consistent position is incredibly important). Deadspace's lead designer, Dino Ignacio, gave an amazing talk of Deadspace's UI at GDC in 2013. This was a powerful presentation for me, and has heavily influenced the way I think about not just game design, but app design, and design in general. Shining Force One of my favorite games of all time is Shining Force. When I moved and started a new school in third grade, I asked every kid in class if they had ever heard of it, and some of my friends I met were because of it. Nostalgia aside, one of the things I loved about Shining Force was the introduction. When you start the game, a little bit of the story starts scrolling in. It stuck with me, and I love the way the text comes in word by word, scrolls down; the experience it creates. Every time I turned the game on, it just felt like I was starting a journey in a fantasy world. Shining Force I introduction Understanding Comics Understanding Comics is an amazing book that has a lot to do with comics, but not as much as the title implies. One of the many concepts it discusses is the concept of audience involvement. It's easier to relate to a stick figure than it is to a realistic drawing of a man. Your imagination sort of fills in the blank. Understanding Comics The more the concept of an object is emphasized, the less realistic it is drawn. Less emphasis is given to their physical appearance. To portray the beauty and complexity of the physical world, however, realism plays a larger part. It's fine for the background in comics to be more realistic, as brick walls and landscapes aren't things audiences identify themselves with. Likewise, in my game I've tried to give the backgrounds and map a little more high fidelity, while the foreground character sprites resemble characters from a SNES or SEGA role playing game. Technology Used Scars of the Untrodden makes heavy use of SVG filters and CSS filters (both built in, and using custom SVG filters). Browser based games have tremendous potential. One reason, I think, is the power of different HTML element types. The <canvas> element can be used to render things that change often. <Div> tags can be overlaid to display text (taking advantage of the browser's built-in text rendering engines, as opposed to writing your own), or to handle UI elements. SVG and D3 can be used to easily handle interactive elements or provide visualizations. The menagerie of different elements available can make the prototyping and development process extremely fast and less bug prone. In Scars of the Untrodden, SVG is the primary technology used to play the game, and D3.js is the primary library used to handle it. A canvas element is overlaid and used when necessary to render particle effects and other things that require frame-by-frame updates. Normal HTML elements are used to draw and handle UI elements. This approach won't work for all games of course, but by leveraging the built-in elements browsers provide, I'm able to quickly iterate and make little or no performance tradeoffs. For some games, like action games, canvas (or webgl) is an obvious choice... but for others, like tactics-based games (Shining Force), there can be benefits to using SVG. In my game, there are few graphic updates each game loop iteration, so for me SVG is a fine fit. Initial Experience Breakdown I'd like to share how I'm designing my game's initial experience. Feel free to check it out before reading about it. General Aestethics Scars of the Untrodden, an HTML5 game built using D3.js. View the introduction This is a fantasy rogue-like game. I want to immediately convey that this takes place in a fantasy world and is centered around exploration. The book, typography, title, and blurred out map hopefully convey this. I like the idea of using a journal in the introduction, as I'm trying to imply that this is a story the player is creating by exploring the world. The journal is also, to some degree, a diegetic interface. The goal is to try to encourage a more immersive experience right from the start. The First Page Let's take a look at the first page; what you immediately see when opening the game: Initial loading / title sequence Like Shining Force, the body of the text fades in word by word. The actual meaning of the text is a bit nebulous, but it hints at the underlying story. It's also a type of visualization (although a bit subtle). As you progress, the text will change based on your progress. It will be a subtle cue, and something that isn't critical to playing the game (but could add a little flavor for those that enjoy it). If you don't want to wait for the text to fade in, you can click it or press escape. This is important as most players don't want to be forced to wait to play, and forcing it on them could be considered bad design. After the text fades in, the name input comes up. It's the only thing that has any behavior when interacting with, so hopefully it's clear enough without being too obvious. The background is white and the font is different. Like Deadspace, I'm trying to immediately establish a consistent design language for interactions. When you see something white with that different font, it means you should (or can) interact with it. Race Selection Race selection After entering your name, you're presented with the option to select a race. Like the name input, the background is also white to imply that it is interactive. When you click the race, the font of the selected race changes as well. Many role playing games allow you to select a race. By providing race selection so soon, I'm trying to imply that this is some sort of fantasy role playing game. There are two races that can be selected, and two that cannot which have the name 'undiscovered'. This is a visualization as well, and it aims to do a couple things:
- Second, by showing other races that are 'undiscovered', it implies that you will be able to unlock them somehow. Hopefully, this also immediately sparks a bit of curiosity. One game that also does this well is A Wizard's Lizard: A Wizard's Lizard's character selection Race Description and Visualization The bonuses for each race hopefully seem like they will have a heavy impact on gameplay, even if you know nothing about gameplay. I'm trying to immediately present the player with significant choices. Selecting human grants +20% exp, but but Elves have a chance to completely avoid all damage. Without knowing anything about the game mechanics, other than what has been implied so far (likely some sort of progression based fantasy game), hopefully the player will already have the sense that they are making significant descisions. More experience or chance to avoid damage? D3.js is used both for the main gameplay, and for drawing visualizations. The visualizations are intentionally nebulous in that no numbers are shown and there is no scale provided. The experience this kind of visualization creates is different than a straight, clean bar chart with numbers. There are a few things I'm trying to accomplish:
  1. The visualization is to, some degree, diegetic. I'm trying to make it look like it's a bar chart that someone could have drawn in their diary. Semi-abstract race visualization Data Visualization in Games - Abstractions The visualization the games provide will provide a sense of what the data means, but they do not fully represent the data. By this, I mean that the goal of the visualizations is to not give you perfect information. The concepts that visualizations in games represent are abstractions. A character's health is an abstraction. In real life, humans don't have hit points. If I can jog a couple miles - does that mean I have 75 stamina? Quantifying these things are tough. How do I translate my programming ability into 'programming' skill points? The point I'm trying to make is that hit points, ability and stats in video games are by nature abstractions of reality. By showing a health bar of exactly how many 'hit points' your character has, you expose the data behind the abstraction, you expose that abstraction for what it is. An abstraction. So, by showing a bar without displaying the 'behind the curtain' value calculation, I think that the visualization can help aide in creating a more immersive experience. In Scars of the Untrodden, I'll rarely (if ever) show the actual number values, and instead will try to keep the visualizations a bit nebulous. Conclusion This game is a work in progress and while a lot of it is coded, I have not yet planned a release date. You can check out the demo of the initial experience. I'm trying to improve my design skills, so I appreciate any suggestions or criticisms. After selecting your character's race, you will then select abilities. You'll explore a procedurally generated world by interacting with a map, hoping from place to place. Some locations may contain battles, or shops, or quests. The map exploration is inspired by FTL, and is built using D3.js and SVG filters: Map Exploration with SVG and Filters My last post explained how to use D3.js to create a fog of war effect like the one I'm using in my game. The battle system is in real time, a sort of mixture between final fantasy and League of Legends. In future posts, I'll go more deeply into other areas of gameplay, design, and more how I use D3.js and a variety of HTML5 elements to create a browser based game which makes use of a variety of browser features. In the meantime, feel free to take a look at the initial experience. Feedback is welcome! View the initial demo

Using D3 and SVG Filters to Create a Fog of War Effect

Sun, 14 Sep 2014 00:00:00 GMT

Simple Fog of War Example Using SVG Filters and Masks. Click to reveal fog The Fog of War is a common type of game data visualization, frequently used in Real Time Strategy (RTS) games. At the core, the idea is simple: areas on the map where you control units (or have explored) are visible, and unexplored areas are dark. This post describes a simple way to achieve this effect for a browser based game using SVG filters and masks, along with a little bit of D3.js. Filters can be not only a powerful prototyping tool, but also an easy way to achieve impressive visual effects for browser based games. Note: Filters are not supported in all browsers. If using filters in production, be sure to be aware of the performance tradeoffs and the browsers your audience uses. View demo. Masks There are many ways to create a fog of war effect, but one potential simple way to think of it as a mask effect. For example:

Data Visualization in Games

Sun, 31 Aug 2014 00:00:00 GMT

Better Group-based Javascript Logging for Browsers

Sun, 24 Aug 2014 00:00:00 GMT

This is the last in a series of posts on logging. The first post describes how group based logging can be a powerful tool , the second post introduces Bragi, a NodeJS logging framework , and this post discusses Bragi for the Browser Bragi, a Javascript Logger Last week I introduced Bragi-Node , a Javascript, NodeJS based logging library. This week I'd like to introduce the browser version of Bragi . My team and I have been using a version of this library for the past year. Next to unit tests (and in some ways even more benefical than them), group-based logging has been the most useful tool in our toolbox. In my previous posts, I talked about some of the benefits of logging and why groups and colors are important, so I'll just briefly mention them here: Groups By group based logging, I mean log messages that are categorized by groups. Not levels (info, warn, error), like most logging libraries I've encountered, but groups. Filtering certain types of messages (and sending them to the console or a remote host) is possible with groups. Bragi also allows namespacing, so you can have a group, like "error:customerController:fetchUsers" - this would be interpreted as an error and it is able to be filtered. We could log with the group "app1:component1:userId", and filter out only log messages from the app1 namespace; or even more fine-grained to show only app1:component1 messages. Or, by using regular expressions (which Bragi supports), we could show all messages that involve userId (which could be a dynamic string of the actual user's ID or whatever you'd like), by specifying to show logs from ".*:userId". Colors My philosophy lately has been to log everything. I liberally liter my code with log messages: every time a function is called or returned, anytime a significant bit of logic is run, etc. Of course, if there's no way to filter the logs and all messages look the same, I'd have a huge problem. It's really a data visualization problem (for me, log messages are data). Color coding groups makes it possible to see any number of groups at once, while still gaining insight from the logs. If you enable all logs and see a color repeating over and over, it means some function or group is being called a lot. Being able to visualize that, especially when a system is running in production, is incredibly useful. Colors are a great visual cue. They can help you regain the context of how the code works by enabling all messages and tracing the flow of execution. It's easier to maintain context when different groups are easily distinguishable. Javascript Browser Logging Bragi itself as a library is new, but the ideas behind it are old. Improvements, suggestions, and criticisms are all welcome. Check out the browser version of Bragi on github . Or, open your console to see an example. Happy logging. BRAGI.log('blog:bragi:browser', 'Hey there. You are reading a post about Bragi, the logger powering this log message'); BRAGI.log('warn', 'And this one! Watch out, pay attention'); BRAGI.log('user:about', 'Using different groups for different information is useful. Looks like you are using %s', window.navigator.userAgent); for(var i=0; i<10; i++){ (function loopClosure(i){ BRAGI.log('group' + i, 'Each group gets a unique color', {curIndex: i}); })(i) } BRAGI.log('blog', 'And here is a log from the base blog group, which is colored the same at the first blog message.'); BRAGI.log('blog:bragi', 'Try it out yourself. Simply run `BRAGI.log(\"groupName\", \"Message\");`. And parameters afterwards are optional, and can be used to show information about objects'); BRAGI.log('user:callToAction', 'Thanks for checking this out. Check it out on github, https://github.com/enoex/Bragi-Browser');

Bragi - A Javascript Logging Library for NodeJS

Sun, 17 Aug 2014 00:00:00 GMT

My first post talked about logging on an abstract level. In this post, I discuss a concrete implementation of those ideas. I’d like to share with you Bragi, a Javascript logging library I wrote that has made my development workflow more efficient and enjoyable. In this first part, I’ll discuss the NodeJS version of Bragi. Next week, I’ll release and discuss the web browser version. *tl;dr: Just want the library? Check out Bragi, a javascript logging library that allows expressive logging, uses colors and symbols, and allows piping logs to numerous outputs (console, file, remote hosts). Note that this is a public, early version which is subject to API changes. Ideas behind Bragi Some of the core concepts driving Bragi are:

By design, there should be many calls to log() inside the application’s codebase and these calls should never need to be removed.

Log output should not be coupled to calls to log(). It should be easy to send the output of log() calls to the console, to a file, or to a remote host. It should even be simple to have the library send your phone a push notifications for certain types of logs.

Logs messages should be structured data - for Bragi, all calls to log() should produce a JSON object with the logged message and some meta info. This makes working with logs easier and allows better integration with third party services like Graylog or Kibana

The logging library itself should not care what you do with the logs, but instead enable you to effortlessly do whatever you wish with them. Before I dive into examples of how to use Bragi, I want to discuss how it differs from many traditional logging approaches. Traditional Logging Breakdown
1. Outputting log messages (either to the console, to a file, a remote host, etc) Normally, these two tasks are bundled together. For example, console.log() is a call to log which immediately prints something. When a log message directly prints something to your console, leaving log messages in a codebase pollutes the application’s output and can make it more difficult to develop or gain insights. The calls to log() and the output of those calls should be decoupled, and it should be possible for the output to be filtered. 1. Calls to log() The paradigm I’ve found most helpful is to leave log messages in code and have a way to filter what is output and how it is outputted (e.g., via console or written to a file). Most libraries I’ve used just have a linear log level setting - e.g., “debug”, “info”, “warn”, “error.” This is a step in the right direction, but it’s not expressive enough. With linear log levels alone, your ability to filter messages is greatly limitted and you have no fine grain control over what is shown. Log Groups and Filtering Bragi uses “log groups.” Instead of a linear log level, each log message belongs to some arbitrary group you create. This allows logging to be more expressive and tailored to your specific application. This allows the traditional “debug”, “info”, “error” log levels; but it also allows having log messages grouped by file name, method name, user id, etc. I’ve found it helpful to have group names separated by a colon (namespaces, in a way). For instance, this allows such fine grain groups such as: “userController:updateUser:name:userId123”. The group name is just a string, so it can be built dynamically - userId could be populated by whatever user is being updated. With groups, filtering becomes easy. We could show all messages from the userController namespace by enabling “userController” logs, or see only calls to updateUser by enabling “userController:updateUser”. If the logging library supports regular expressions (Bragi does), then we could also see all logs across the entire system for a specific user by adding /.*:userId123/ to the enabled groups. Expressive log groups can provide a complete and fully controllable view into exactly what your code is doing at any time by any metric or facet you desire. 2. Output of Logs: Transports Bragi uses the notion of “transports” (inspired by [winston]), which determine what is done with a log message. By default, Bragi will print colored log messages to the console. Currently, it can also write to a file or output JSON. When log() is called, an object is created based on the group and passed in message. This object is augmented with some meta information, such as the time the message was logged and the calling function’s name (if it has one). Additionally, any extra arguments passed into log() are added onto a properties key. In Bragi, Console is the only transport enabled by default. To remove all transports, you can call transports.empty(), and to add a transport transports.add( new Tranport...() ) can be called. Writing good log messages Like naming variables, writing a good log message is not trivial. Some of the problems around writing good messages are tied to how code is structured. One thing I’ve found to be very helpful is to name all functions, so when looking at a stack trace I never see “anonymous function” and have to wonder where it is. Another thing that has helped me is to use colors and symbols. Color is a powerful way to visualize information (e.g., all error messages have a red background with white text. Whenever you see it, you know immediately that it is an error). Bragi provides a function, logger.util.print(message, color), which takes in a message {String} and a color {String} (like ‘red’ or ‘green’), and returns the passed in message colored by the passed in color. This is useful for printing messages that contain color. For instance: Symbols are also incredibly useful way to encode data in an easy to consume form. Using Symbols In Logs Symbols provide powerful visual cues. Looking at a sea of text is daunting, but if the text has various ✔︎ or ✗ or ☞, your eyes are drawn towards them. In fact, I can guess what happened when you saw this paragraph: the symbols initially jumped out at you and you directed your focus towards them, maybe even reading the word “various” before jumping back to the top of the paragraph to read it. These cues allow you to quickly filter out certain messages. When you setup your logging, if you give all asynchronous calls an ✗ symbol, they will become much easier to spot. Or maybe you give all warnings a ☞ symbol. Or maybe before an async request is made you print a ◯ symbol, then a ◉ symbol when the async process is finished. Bragi provides some UTF-8 symbols, accessible via var logger = require(‘brag’); // symbols can be accessed via the `util` property. // It is a dictionary of symbols, such as logger.util.symbols.success console.log( logger.util.symbols ); How to use Bragi The core of Bragi involves a call to log(). It takes in two required parameters and any number of additional objects. For instance: var logger = require(‘bragi’); logger.log(‘group1’, ‘Hello world’); logger.log(‘group1:subgroup1’, ‘I can also log some objects’, { key: 42 }); Configuring Options Filtering is a key feature of what makes this kind of logging powerful. With Bragi, you can specify what logs to show by providing a groupsEnabled array which can contain strings or regular expressions. If group1:subgroup1 is a value in the array, all messages that match group1:subgroup1, including nested subgroups, would get logged. If groupsEnabled is a boolean with a value of true, everything will be logged. Similarly, you can specify log messages to ignore via the groupsDisabled key (also an array). It works the same as groupsEnabled, but in reverse. It will take priority over groups specified in groupsEnabled. This is useful, for instance, if you want to log everything except some certain messages. As with groupsEnabled, it is an array which can take in strings or regular expressions. More configuration information can be found in Bragi's source code. Conclusion Bragi is the result of me trying to formalize and publicly release a logging library I’ve been using for the past couple of years. It’s worked great for my team and me, so I thought others might find it useful. Bragi is in the incipient stage so the API will likely change. Criticisms and improvements are welcome, and I’ll be updating it and adding more transports throughout the next few weeks. Bragi is not just for NodeJS - next week, I’ll release and discuss the web browser version. You can find Bragi, a Javascript logger on Github

How Logging Made me a Better Developer

Sun, 10 Aug 2014 00:00:00 GMT

I think logging is one of the most powerful tools in a programmer's toolbox. Unfortunately, it's supremely underutilized. Logging gives you data about what your code is doing. Over the past couple years, I've found logging helps me to manage complexity, communicate my code to other developers (and vice versa), and allows me to rapidly develop and debug software. As simple and silly as it may seem; for me, logging is unequivocally the most beneficial tool in my toolbox. This is the first part in a two part series on logging. This post describes why I think logging is important on an abstract level, and the second post will discuss a concrete implementation of a Javascript logging library that uses the concepts outlined here When I first started learning to program, I remember using log statements a lot. Almost all introductory programming classes or tutorials demonstrate concepts by using logging, or print(), or some other function to print output to the console. What quicker way exists to verify your code is doing what you expect it to (or doing anything at all)? As I learned more about how to program, I stopped littering my code with log statements. I thought logging was a sort of novice thing to do. Over the past couple years, however, I've gone back to my logging roots. Many of my peers have little to no logging in their codebases, and many - if not most - popular third party libraries are devoid of any logging. Of course there are exceptions, but I'm confused why finding well logged code is not the norm. Why is this? I don't know, and I'm not going to try to answer it. I can only share what has worked for me, and why I've found logging to be incredibly useful. Why Log? Liberal use of logging has a plethora of benefits. At the highest level, programs are hard to write and manage because they are complex. The complexity of the problem you're solving, the building of abstractions, is the hard part. Logging, unit tests, agile programming, test driven development, scrum, continuous integration, third party framework X or Y; or any other tool really does not decreases complexity (the essence of programming). However, logging has helped both myself and my team to manage that complexity more efficiently. Not only has it helped ease the communication of what we built, logging also provides numerous other beneficial side effects. What I mean by logging I'm going to describe a lot of the benefits logging has provided me. However, the positive effects are affected by what is being logged and how often it occurs. I lean towards logging nearly everything. When a function is called, I log that it has been called along with any passed in arguments, the time it was called, and in Javascript, the name of the function that called it. I also log before a function returns, along with the time and any relevant return data. I log when asynchronous calls return. I log when significant logic changes happen. I leave these log messages in the code; I don't comment them out or remove them (of course, I don't have the output of all log messages always enabled - I'll cover how I filter the output of log messages later). Benefits This approach might sound ugly and make it seem like the code would be cluttered and unreadable. As crazy as it might sound though, this method allows me to develop code more quickly and effectively than unit tests, can communicate what the code is doing better than comments, and is easier and faster to implement than nearly any other tool or technique I've used. Visibility into code helps manage complexity. For me, the primary benefit of logging is visibility into what my code is doing. Breakpoints can do this to some extent - but they require manual setting and clearing. Unit tests provide significant advantages as well, but they don't let you see what your code is doing (important when it's running in production, but also even a consideration when you're developing). Sufficient logging allows answering nearly any question about what a program is doing. There are two sides I see to increased visibility: the first is visibility into what your code is doing after it's running and people are using the software you wrote. The second is visibility into your code during development. Visibility after shipping Seeing what your code is doing when it's being used is extremely beneficial if you're developing any kind of product that changes over time. With logging, if you have an API, you can see what endpoints are being hit and when. With minimal additional sophistication to a logging framework, you could even track the time for every request / response for free. If you write a game, you can track for every player how many units are killed or what the average score is at different points of time in the game. More data allows more questions to be asked and answered. The more you log, the more data you have. Visibility while developing Just as useful as visibility into shipped code is visibility into code during development. By logging when a function is called and returned, I get on demand stack traces for free. I don't have to know a-priori that I want a stack track. If a related and unanticipated edge case bug occurs in some other area of my code when I'm developing, I wouldn't know to set a breakpoint. With logging, it's almost as if I set breakpoints everywhere, so I can trace the flow of execution (and a lot of state) for every call after they've happened. This, of course, isn't convenient just for me. Communication Logging allows other develops to see exactly code is doing. Unit tests are wonderful for many reasons, but they aren't great at communicating what code does - only that it does or doesn't do something. They help to verify code works after changing something, but how effective are they in helping to understand how the code works? With good logging in place, it's easier for other developers to see exactly what the code is doing. By enabling all logging messages, other developers can follow through the execution of any parts of the program they desire without needing to manually set break points. Explicit comments. To me, the ideal commenting system involves small functions with a sentence or two high level description at the top of the function describing its purpose. This, coupled with well named variables, is expressive (e.g., "var x=4" doesn't count - this is position, some random variable, what?). Code should describe itself, but those descriptions often aren't enough to give a high level overview of what's happening. In reality, functions often times get to be larger than anticipated, and due to various non-programming constraints (e.g., time), we often don't have the luxury (or are too lazy) to go back and write proper comments or cleaner code. Logging helps solve this problem. By sprinkling a function with log messages, you're implicitly providing a comment about what the should be doing at that point. When the program runs, it explicitly logs what it is doing. Reading and understanding a function's behavior is easier when there are comments, but if you can replace a lot of comments with log messages, you get both the benefits of documentation and explicit information when a program runs. How I log I've found the benefits of logging to be only as good as what and how I'm logging. In the past, I would write a log statement to validate some assumptions, but then remove the log statement afterwards. Nobody wants their code producing irrelevant output. If the log statements were once helpful, however, I think they can continue to be helpful. The trick is to leave the messages in, but have a method of filtering them. The following spec has worked wonderfully for me. A sample log message might look like: logger.log("filename:methodname", "some message: %s", "replaced string"); First, we need a way to log messages. The logging library exposes a "log" function which takes in two (and possibly more) parameters:

group: a {string} specifying the group the log message belongs to. Subgroups are delineated by colons (:)
message : a {string} specifying the message to log. If it contains formatting parameters (e.g., http://nodejs.org/api/util.html#utilutilformat_format ), additional parameters can be passed in to be replaced.
n more arguments: objects that will be formatted by the message string Next, we need a way to filter the messages. The idea is to have a bunch of log messages and leave them in without negatively impacting the application's output. By specifying the group(s) a log message belongs to, we can filter by group and any level of subgroups. One possible implementation, the approach I took, is to provide a logLevel parameter which is takes in an array of strings specifying what to log (e.g., "filename" would log anything that matched "filename", as well as any subgroups: filename:group1", "filename:group1:subgroup1", etc.). Each time log() is called, the passed in log group is checked against the valid log groups. Conclusion I believe logging is a terribly underutilized tool that can provide tremendous benefits. Logging provides data about code. This data allows you to gain insights into what your code is doing and how it's doing it. Along with increased visibility into code, logging enhances communication about it. For my team and me, logging has been incredibly helpful. I think it's a practice that should be more widely used. In my next post, I'll discuss the concrete implementation of a logging library I developed based on these concepts that I've been using for the past couple years.

How to Build an Entity Component System Game in Javascript

Sun, 03 Aug 2014 00:00:00 GMT

View the source code or play Rectangle Eater Creating and manipulating abstractions is the essence of programming. There is no "correct" abstraction to solve a problem, but some abstractions are better suited for certain problems than others. Class-based, Object Oriented Programming (OOP), is the most widely used paradigm for organizing programs. There are others. Prototypical based languages, like Javascript, provide a different way of thinking around how to solve problems. Functional programming provides yet another completely different way to think about and solve problems. Programming languages are just one area where a different mindset can help solve problems better. Even within a class based or prototype based language, many methods exist for structuring code. One approach I've grown to love is a more data driven approach to code. One such technique is Entity-Component-System (ECS). While it is a general architecture pattern that could be applied to many domains, the predominant uses of it are in game development. In this post, I'll cover the basic topics of ECS and we'll build a basic HTML5 game about eating rectangles - oh-so creatively called "Rectangle Eater". Entity-Component-System Discovering Entity Component System (ECS) was an "ah-hah" moment for me. With ECS, entities are just collections of components; just a collection of data.
Entity: An entity is just an ID
Component: Components are just data.
System: Logic that runs on every entity that has a component of the system. For example, a "Renderer" system would draw all entities that have a "appearance" component. With this approach, you avoid having to create gnarly inheritance chains. With this approach, for example, a half-orc isn't some amalgamation of a human class and an orc class (which might inherit from a Monster class). With this approach, a half-orc is just a grouping of data. An entity is just a like a record in a database. The components are the actual data. Here's a high level example of what the data might look like for entities, shown by ID and components. The beauty of this system is that you can dynamically build entities - an entity can have whatever components (data) you want. | | component-health | component-position | component-appearance | |---------|-------------------|--------------------|-----------------------| |entity1 | 100 | {x: 0, y: 0} | {color: green} | |entity2 | | {x: 0, y: 0} | | |entity3 | | | {color: blue} | Dynamic Data Driven Design Everything is tagged as an entity. A bullet, for instance, might just have a "physics" and "appearance" component. Entity Component System is data driven. This approach allows greater flexibility and more expression. One benefit is the ability to dynamically add and remove components, even at run time. You could dynamically remove the appearance component to make invisible bullets, or add a "playerControllable" component to allow the bullet to be controlled by the player. No new classes required. This can potentially be a problem as systems have to iterate through all entities. Of course, it's not terribly difficult to optimize and structure code so not all entities are hit each iteration if you have too many, but it's helpful to keep this constraint in mind, especially for browser based games. Assemblages One benefit of a Class based approach is the ability to easily create multiple objects of the same type. If I want one hundred orcs, I can just create a hundred orc objects and know what properties they'll all have. This can be accomplished with ECS through an abstraction called an assemblage, which is just a way to easily create entities that have some grouping of components. For instance, a Human assemblage might contain "position", "name", "health", and "appearance" components. A Sword assemblage might just have "appearance" and "name". One benefit this provides over normal Class inheritance is the ability to easily add on (or remove) components from assemblages. Since it's data driven, you can manipulate and change them programmatically based on whatever parameters you desire. Maybe you want to create a ton of humans but have some of them be invisible - no need for a new class, just remove the "appearance" component from that entity. Code This is not an attempt to build out a robust ECS library. This is designed to be an overview of Entity Component System implemented in Javascript. It's not the best or most optimized way to do it; but it can provide a foundation for a concrete understanding of how everything fits together. All code can be found on github. Entity The abstraction is that an entity is just an ID; a container of components. Let's start by creating a function which we can create entities from. Each entity will have just an id and components property. (Note: the follow expects a global ECS object to exist, which looks like var ECS = {};) ECS.Entity = function Entity(){ // Generate a pseudo random ID this.id = (+new Date()).toString(16) + (Math.random() * 100000000 | 0).toString(16) + ECS.Entity.prototype._count; // increment counter ECS.Entity.prototype._count++; // The component data will live in this object this.components = {}; return this; }; // keep track of entities created ECS.Entity.prototype._count = 0; ECS.Entity.prototype.addComponent = function addComponent ( component ){ // Add component data to the entity // NOTE: The component must have a name property (which is defined as // a prototype protoype of a component function) this.components[component.name] = component; return this; }; ECS.Entity.prototype.removeComponent = function removeComponent ( componentName ){ // Remove component data by removing the reference to it. // Allows either a component function or a string of a component name to be // passed in var name = componentName; // assume a string was passed in if(typeof componentName === 'function'){ // get the name from the prototype of the passed component function name = componentName.prototype.name; } // Remove component data by removing the reference to it delete this.components[name]; return this; }; ECS.Entity.prototype.print = function print () { // Function to print / log information about the entity console.log(JSON.stringify(this, null, 4)); return this; }; View Source To create a new entity, we'd simply call it like: var entity = new ECS.Entity();. There's not a lot going on in the code here. First, in the function itself, we generate an ID based on the current time, a call to Math.random(), and a counter based on the total number of created entities. This ensures we get a unique ID for each entity. We increment the counter (prototype properties are shared across all object instances; sort of similar to a class variable). Then, we create an empty object to stick components (the data) in. We expose an addComponent and removeComponent function on the prototype (again, single functions in memory shared across all object instances). Each take in a component object and add or remove the passed in component from the Entity. Lastly, the print method simply JSON-ifies the entity, providing all the data. We could use this to dump out and reload data later (e.g., saving). So, at the core, an Entity is little more than an object with some data properties. We'll cover how to create multiple Entities soon, and where assemblages fit in. Component Here's where the data part of data driven programming kicks in. I've structured components similarly to entities; for example: ECS.Components.Health = function ComponentHealth ( value ){ value = value || 20; this.value = value; return this; }; ECS.Components.Health.prototype.name = 'health'; To get a Health component, you'd simply create it with new ECS.Components.Health( VALUE ) where VALUE is an optional starting value (20 if nothing is passed in). Importantly, there is a name property on the prototype which tells the Entity what to call the component. For example, to create an entity then give it a health component: var entity = new ECS.Entity(); entity.addComponent( new ECS.Components.Health() ); That's all that is required to add a component to an entity. If we printed the entity out now (entity.print();), we'd see something like: { "id": "1479f3d15bd4bf98f938300430178", "components": { "health": { "value": 20 } } } That's it - it's just data! We could change the entity's health by modifying it directly, e.g., entity.components.health.value = 40; We can have any kind of data nesting we want; for example, if we created a position component with x and y data values, we'd get as output: { "id": "1479f3d15bd4bf98f938300430178", "components": { "health": { "value": 20 }, "position": { "x": 426, "y": 98 } } } To keep this post manageable, here's all the code for all these components used in the game Since components are just data, that don't have any logic. (Depending on what works for you, you could add some prototype functions to components that would aide in data calculations, but it's helpful to view components just as data). So we have a bunch of data now, but to do anything interesting we need to run operations on it. That's where Systems come in. System Systems run your game's logic. They take in entities and run operations on entities that have specific components the system requires. This way of thinking is a bit inverted from typical Class based programming. In Class based programming, to model a cat, a Cat Class would exist. You'd create cat objects and to get the cat to meow, you'd call the speak() method. The functionality lives inside of the object. The object is not just data, but also functionality. With ECS, to model a Cat you'd first create an entity. Then, you'd add some components that cats have (size, name, etc.). If you wanted the entity to be able to meow, maybe you'd give it a speak component with a value of "meow". The distinction here though is that this is just data - maybe it looks like: { "id": "f279f3d85bd4bf98f938300430178", "components": { "speak": { "sound": "meeeooowww" } } } The entity can do nothing by itself. So, to get a "cat" entity to speak, you'd use a speak System. (Note: the component name and system name do not have to be 1:1, this is just an example. Most systems use multiple different components). The system would look for all entities that have a speak component, then run some logic - plugging in the entity's data. The functionality happens in Systems, not on the objects themselves. You'll have many different systems that are tailored for your game. Systems are where your main game logic lives. For our rectangle eating game, we only need a few systems: collision, decay, render, and userInput. The way I've sturctured systems is to take in all entities (here, the entities are an object of key:value pairs of entityId: entityObject). Let's take a look at a snippet of the render system. Note, the systems are just functions that take in entities. ECS.systems.render = function systemRender ( entities ) { // Here, we've implemented systems as functions which take in an array of // entities. An optimization would be to have some layer which only // feeds in relevant entities to the system, but for demo purposes we'll // assume all entities are passed in and iterate over them. // This happens each tick, so we need to clear out the previous rendered // state clearCanvas(); var curEntity, fillStyle; // iterate over all entities for( var entityId in entities ){ curEntity = entities[entityId]; // Only run logic if entity has relevant components // // For rendering, we need appearance and position. Your own render // system would use whatever other components specific for your game if( curEntity.components.appearance && curEntity.components.position ){ // Build up the fill style based on the entity's color data fillStyle = 'rgba(' + [ curEntity.components.appearance.colors.r, curEntity.components.appearance.colors.g, curEntity.components.appearance.colors.b ]; if(!curEntity.components.collision){ // If the entity does not have a collision component, give it // some transparency fillStyle += ',0.1)'; } else { // Has a collision component fillStyle += ',1)'; } ECS.context.fillStyle = fillStyle; // Color big squares differently if(!curEntity.components.playerControlled && curEntity.components.appearance.size > 12){ ECS.context.fillStyle = 'rgba(0,0,0,0.8)'; } // draw a little black line around every rect ECS.context.strokeStyle = 'rgba(0,0,0,1)'; // draw the rect ECS.context.fillRect( curEntity.components.position.x - curEntity.components.appearance.size, curEntity.components.position.y - curEntity.components.appearance.size, curEntity.components.appearance.size * 2, curEntity.components.appearance.size * 2 ); // stroke it ECS.context.strokeRect( curEntity.components.position.x - curEntity.components.appearance.size, curEntity.components.position.y - curEntity.components.appearance.size, curEntity.components.appearance.size * 2, curEntity.components.appearance.size * 2 ); } } }; The logic here is simple. First, we clear the canvas before doing anything. Then, we iterate over all entities. This system renders entities, but we only care about entities that have an appearance and position. In our game, all entities have these components - but if we wanted to create invisible rectangles that the player could interact with, all we'd have to do is remove the appearance component. So, after we've found the entities which contain the relevant data for the system, we can do operations on them. In this system, we just render the entity based on the colors properties in the appearance component. One benefit too is that we don't have to set all the appearance properties here - we might set some in the collision system, or in the health system, or in the decay system; we have complete flexibility over what roles we want to assign to each system. Because the systems are driven by data, we don't have to limit our thinking to just "methods on classes and objects." We can have as many systems as want, as complex or simple as we want that target whatever kinds of entities we want. Overview of Rectangle Eater's systems:
collision: Handles collision, updating the data for health on collision, and removing / adding new entities (rectangles). Bulk of the game's logic.
decay: Handles rectangles getting small and losing health. Any entity with a health component (e.g., most rectangles and the player controlled rectangle) will be affected. This is where a lot of the "fun" configuration happens. If the rectangle decays and goes away too fast then the game is too hard - if it's too slow, it's not fun.
render: Handles rendering entities based on their appearance component.
userInput: Allows the player to move around entities that have a PlayerControlled component. In the collision system of our game, we check for collisions between the user controlled entity (specified by a PlayerControlled component and handled via the userInput system) and all other entities with a collision component. If a collision occurs, we update the entity's health (via the health component), remove the collided entity immediately (the systems are data driven - there's no problem dynamically adding or removing entities on a per system level), then finally randomly add some new rectangles (most of these will decay over time, and when they get smaller they give you more health when you collide with them - something else we check for in this collision system). Like in a normal game loop, the order which the systems gets called is also important. If your render before the decay system is called, for example, you'll always be a tick behind. Gluing it all together The final step involves connecting all the pieces together. For our game, we just need to do a few things:
Setup the initial entities
Setup the order of the systems which we want to use
Setup a game loop, which calls each system and passed in all the entities
Setup a lose condition 1. Let's take a look at the code for setting up the initial entities and the player entity: var self = this; var entities = {}; // object containing { id: entity } var entity; // Create a bunch of random entities for(var i=0; i < 20; i++){ entity = new ECS.Entity(); entity.addComponent( new ECS.Components.Appearance()); entity.addComponent( new ECS.Components.Position()); // % chance for decaying rects if(Math.random() < 0.8){ entity.addComponent( new ECS.Components.Health() ); } // NOTE: If we wanted some rects to not have collision, we could set it // here. Could provide other gameplay mechanics perhaps? entity.addComponent( new ECS.Components.Collision()); entities[entity.id] = entity; } // PLAYER entity // Make the last entity the "PC" entity - it must be player controlled, // have health and collision components entity = new ECS.Entity(); entity.addComponent( new ECS.Components.Appearance()); entity.addComponent( new ECS.Components.Position()); entity.addComponent( new ECS.Components.Collision() ); entity.addComponent( new ECS.Components.PlayerControlled() ); entity.addComponent( new ECS.Components.Health() ); // we can also edit any component, as it's just data entity.components.appearance.colors.g = 255; entities[entity.id] = entity; // store reference to entities ECS.entities = entities; Note how we can modify any of the component data directly. It's all data that can be manipulated however and whenever you want! The player entity step could be even further simplified by using assemblages, which are basically entity templates. For instance (using our assemblages): entity = new ECS.Assemblages.CollisionRect(); entity.addComponent( new ECS.Components.Health()); entity.addComponent( new ECS.Components.PlayerControlled() ); 2. Next, we setup the order of the systems: // Setup systems // Setup the array of systems. The order of the systems is likely critical, // so ensure the systems are iterated in the right order var systems = [ ECS.systems.userInput, ECS.systems.collision, ECS.systems.decay, ECS.systems.render ]; 3. Then, a simple game loop // Game loop function gameLoop (){ // Simple game loop for(var i=0,len=systems.length; i < len; i++){ // Call the system and pass in entities // NOTE: One optimal solution would be to only pass in entities // that have the relevant components for the system, instead of // forcing the system to iterate over all entities systems[i](ECS.entities); } // Run through the systems. // continue the loop if(self._running !== false){ requestAnimationFrame(gameLoop); } } // Kick off the game loop requestAnimationFrame(gameLoop); 4. Finally, a lose condition // Lose condition this._running = true; // is the game going? this.endGame = function endGame(){ self._running = false; document.getElementById('final-score').innerHTML = +(ECS.$score.innerHTML); document.getElementById('game-over').className = ''; // set a small timeout to make sure we set the background setTimeout(function(){ document.getElementById('game-canvas').className = 'game-over'; }, 100); }; View on github Now, we can kick off the game (provided the html has been set up)! Play Rectangle Eater Conclusion Programming is a complex endeavor by nature. We program in abstractions, and different frameworks for thinking can make certain problems easier to solve. Data driven programming is one framework for thinking of how to write programs. It's not the best fit for all problems, but can make some problems much easier to solve and understand. Thinking of code as data is a powerful concept. Entity Component System is a pattern that fits game development well. Try taking the passenger seat. Try letting data drive your code. View the source code or play Rectangle Eater hljs.initHighlightingOnLoad();