by Brujo Benavides Disclaimer Brace yourselves… a long post is coming. It took me too long to write this blog post and the main reason is that it encompasses many many different topics. This will be a blog post about Hackathons TDD Game development Data Type abstraction in functional languages Erlang bitstring syntax RESTful APIs multiple tools like cowboy, mixer, trails, swagger, lasse, etc. History A long time ago, when I was a little kid, I started programming in and, as many of you might know, QBasic came with two little games in it. One of them was Nibbles QBasic Fast-forward 25 years… and you’ll find me at Erlang Solutions trying to come up with the subject for our next with the help of and . We wanted a multiplayer game that could be watched on a single screen. we came up with ! Hackathon Roberto Romero Hernán Rivas Acosta Of course serpents Hackathons Every year at Erlang Solutions we all take one day off from our projects and we spend it all together celebrating what we love the most: . In 2014 we ran a competition with awesome results. For 2015’s edition, we decided to come up with a multi-player game where the organisers set up the server and the teams developed the clients. The code that I will be showing through the rest of this blog post, it all comes from the game server that Hernán, Roberto and myself developed. programming “build your app in just one day” Goals The main goal of was of course to be used for the Hackathon. But I had a hidden agenda for it as well: Since this project was going to be open-sourced on github, I wanted to use it as a case to show how we work. I wanted to be able to get people on IRC, erlang-questions, reddit, stackoverflow, etc. that asks questions like “hey! how do you build a web-server in Erlang?” and tell them “look here. This is how you do it!”. With that in mind, we faced this project as if it was a client project and, turns out, our (our fellow devs) were in fact one of the toughest clients we have ever faced. serpents clients Architecture So, how did we build a multiplayer server for a serpent’s game? We started by dividing it into 3 main components: a web page that displayed the progress of the games. a web server that served the webpage and provided a RESTful API for it to be updated in . real-time a game server that provided the means for clients to connect to it. For the web page we used plain HTML and some Javascript (you can tell how that is not really interesting to me at least :P). What interesting is the part. We implemented that one (as we usually do) over . During a game, the website looked like this: is real-time SSE From the server perspective, we implemented the RESTful API using on and we documented it with . It ended up looking like this: cowboy trails swagger On the other side, we decided to give client devs 2 options. They could just use the same RESTful API and SSE connection to communicate with the server, or they could use our protocol. HDP is a blazingly fast protocol that runs on UDP. It was developed by Hernán and documented in for all to use. It’s specialised for serpents, but it can be replicated in other projects with ease. HDP kafka style Internal Architecture Internally, as you can see on github, the code is divided in multiple folders and multiple modules that we could test individually. One one side, we had the basic building blocks of the game: the rules (in ) implemented as a per game and its entities (represented as or , each one with its own module and opaque type). You can see our approach in : spts_core gen_fsm Data Types Models spts_serpents %%% @doc Serpent model-module(spts_serpents).-author('elbrujohalcon@inaka.net').-type status() :: alive | dead.-type name() :: binary().-opaque serpent() :: #{ name => name() , numeric_id => pos_integer() , token => binary() , body => [spts_games:position()] , direction => spts_games:direction() , food => pos_integer() , status => status() }.-export_type([serpent/0, status/0, name/0]).-export([new/6]).-export([ name/1 , numeric_id/1 , direction/1 , direction/2 , to_json/1 , to_json/2 , to_binary/2 % ... ]).-spec name(serpent()) -> name().name(#{name := Name}) -> Name.-spec direction( serpent(), spts_games:direction()) -> serpent().direction(Serpent, Direction) -> Serpent#{direction := Direction}.% ... We also had multiple cowboy handlers for the different endpoints of our API. All of them were built using to “inherit” functions from the . mixer spts_base_handler %%% @doc /games/:game_id/serpents handler-module(spts_serpents_handler).-author('elbrujohalcon@inaka.net').-include_lib("mixer/include/mixer.hrl").-mixin([{ spts_base_handler , [ init/3 , rest_init/2 , allowed_methods/2 , content_types_accepted/2 , content_types_provided/2 , resource_exists/2 ] }]).-export([ handle_post/2 , trails/0 ]).-type state() :: spts_base_handler:state().-behaviour(trails_handler).-spec trails() -> trails:trails().trails() -> Metadata = #{ post => #{ tags => ["serpents"] , description => "Adds a serpent to a game" , consumes => ["application/json"] , produces => ["application/json"] , parameters => [ spts_web:param(request_body) , spts_web:param(game_id) ] } }, Path = "/api/games/:game_id/serpents", Opts = #{path => Path}, [trails:trail(Path, ?MODULE, Opts, Metadata)].% ... To report events from the core to either the SSE or the HDP clients, we used but, to ease our lives we implemented a simple handler that, in turn, required only one function to be implemented in your client : . We called it . We used that same handler to write tests for the core without depending on any type of client. gen_event gen_event notify(pid(), event()) [spts_gen_event_handler](https://github.com/inaka/serpents/blob/master/src/spts_gen_event_handler.erl) For HDP, we wrote an asynchronous UDP listener which starts a for each client that (there are no actual connections in UDP). The simplicity of that comes from the fact that we abstracted all the protocol parsing/validation logic to its own module: . That module in itself is a great example of the power of Erlang’s . It showcases list-comprehensions, combined with binary-comprehensions and a lot of amazing binary pattern-match expressions. My favourite: gen_server connects spts_hdp bit syntax %% @doc Parses a list of serpent diffs.%% Each one includes the serpent id and the%% length of its body, followed by each of%% the body cells.parse_diff_serpents(0, Next, Acc) -> {lists:reverse(Acc), Next};parse_diff_serpents( N, << SerpentId:?UINT , BodyLength:?USHORT , Body1:BodyLength/binary , Body2:BodyLength/binary , Next/binary >>, Acc) -> Body = <<Body1/binary, Body2/binary>>, Serpent = #{ id => SerpentId , body => [ {Row, Col} || <<Row:?UCHAR, Col:?UCHAR>> <= Body] }, parse_diff_serpents(N-1, Next, [Serpent|Acc]). Development Methodology And, to create all this, we used our usual approach: . We worked with for that and you can see the somewhat long list of test suites we implemented . We’ve written many blog posts about TDD, code-coverage and even meta-testing so I’ll not go over it again here. Just keep in mind that if you need examples of those things, you have plenty around here. TDD common_test here The Clients And if you are asking yourself Yes, they are . I’ve developed all of them myself and you can create your own either starting from scratch or using . are there any client examples out there? here spts_cli The Outcome Conclusions We ended up complying with both of my goals. On the one hand, I can say we had an extraordinary Hackathon with lots of people happily playing while coding. On the other hand, now we have a great example of how we build stuff at Erlang Solutions to show the world. And you can enjoy it, too! just do… $ git clone https://github.com/inaka/serpents.git$ cd serpents$ make$ _rel/serpents/bin/serpents start …and open in your browser to start playing! http://localhost:8585 And, of course, as I did with Nibbles when I was just a kid, the funniest part starts when you start modifying the code to make the serpents fatter, thinner, randomly drunk after eating a … poisoned fruit I to implement that! Bye all, 9-year-old me has something important to do… Oh, man! have Originally published at www.erlang-solutions.com on April 26, 2018. This blog post was originally written for inaka.net on 13 November 2015.
