Forem: Héctor Ramón

Coffee - An opinionated 2D game engine for Rust

Héctor Ramón — Sun, 28 Apr 2019 15:30:09 +0000

Coffee is an opinionated 2D game engine for Rust focused on simplicity, explicitness, and type-safety.

Coffee is in a very early stage of development. Active development is
planned during 2019 (and hopefully beyond that!). Many basic features are still
missing, some dependencies are experimental, and there are probably many
bugs. Feel free to contribute!

Features

Declarative, type-safe asset loading
Loading screens with progress tracking
Built-in debug view with performance metrics
Fixed timestep
Explicit, easy to use, hardware-accelerated 2D graphics API
Multiplatform support leveraging OpenGL, Vulkan, Metal, D3D11, and D3D12
Texture array support
Explicit and efficient batched draws
Off-screen rendering
TrueType font rendering

Overview

Here is a minimal example that will open a window:

use coffee::{Game, Result, Timer};
use coffee::graphics::{Color, Window, WindowSettings};

fn main() -> Result<()> {
    MyGame::run(WindowSettings {
        title: String::from("A caffeinated game"),
        size: (1280, 1024),
        resizable: true,
    })
}

struct MyGame {
    // Your game state goes here...
}

impl Game for MyGame {
    type View = (); // No view data.
    type Input = (); // No input data.

    const TICKS_PER_SECOND: u16 = 60; // Update rate

    fn new(_window: &mut Window) -> Result<(MyGame, Self::View, Self::Input)> {
        // Load your game assets here. Check out the `load` module!
        Ok((MyGame { /* ... */ }, (), ()))
    }

    fn update(&mut self, _view: &Self::View, _window: &Window) {
        // Update your game here
    }

    fn draw(&self, _view: &mut Self::View, window: &mut Window, _timer: &Timer) {
        // Clear the current frame
        let mut frame = window.frame();
        frame.clear(Color::BLACK);

        // Draw your game here. Check out the `graphics` module!
    }
}

Repository

If you want to know more, check out the repository on GitHub!

hecrj / coffee

An opinionated 2D game engine for Rust

Coffee

An opinionated 2D game engine for Rust focused on simplicity, explicitness, and type-safety.

Coffee is in a very early stage of development. Many basic features are still missing, some dependencies are experimental, and there are probably many bugs. Feel free to contribute!

Features

Responsive, customizable GUI
Declarative, type-safe loading screens with progress tracking
Built-in debug view with performance metrics
Fixed, deterministic timestep
Explicit, easy to use, hardware-accelerated 2D graphics API
Multiplatform support leveraging OpenGL, Vulkan, Metal, D3D11, and D3D12
Explicit and efficient batched draws
Mesh support
Texture array support
Off-screen rendering
TrueType font rendering
Gamepad support

And more! Check out the examples to see them in action.

Usage

Add coffee as a dependency in your Cargo.toml and enable a graphics backend feature (opengl, vulkan, metal, dx11, or dx12):

coffee = { version = "0.4", features = ["

…

View on GitHub

Stop coupling logic with your HTTP layer!

Héctor Ramón — Tue, 30 Oct 2018 19:11:41 +0000

As a developer, there is one issue that I tend to notice in many codebases: logic coupled with a specific communication layer.

This issue is especially common in the controllers of most web backends, where application logic is usually intertwined with access to the HTTP layer. It is not surprising. Many documentation examples of some of the most well-known frameworks (Rails, Django, Flask, Phoenix, etc.) have this issue.

But, what do I mean when I say "logic intertwined with access to the HTTP layer"? Let's take a look at how a simple login endpoint could be implemented in Ruby on Rails:

class UsersController < ApplicationController
  def login
    user = User.find_by(email: params[:email])

    unless user.password_match?(params[:password])
      return error_response(:invalid_credentials)
    end

    json_response(auth_token: Tokens.auth(user))
  end
end

Simple, right? But... How do we use this UsersController class? How do we test our login logic? Who populates params? What data does it need? The public contract of this code is not clear at all! We have a class with a method that takes no arguments and uses internal (hidden) state to do its job.

When code cannot be easily used in isolation, it becomes harder to understand, test and debug. We should try to avoid it as much as possible.

The code above is tying the logic of the function to some specific communication layer (HTTP, in this case). Using params and json_response forces us to be aware of this layer every time that we want to use this login method.

We can isolate the logic of our endpoint:

ApiLogin = ->(email:, password:) do
  user = User.find_by(email: email)
  return { data: nil, errors: [:invalid_credentials] } unless user.password_match?(password)

  { data: { auth_token: Tokens.auth(user) }, errors: [] }
end

This is now a communication-agnostic function. Its input (email and password) and its output (a simple hash with data and errors) are explicit. Therefore, we can test it very easily:

ApiLogin.call(email: "some@email.com", password: "12345678")
# => { data: { auth_token: "..." }, errors: [] }

Now, we just need to connect this function to our communication layer. We can use an ApplicationController, like before:

class UsersController < ApplicationController
  def login
    response = ApiLogin.call(email: params[:email], params[:password])

    if response.fetch(:errors).empty?
      json_response(response.fetch(:data))
    else
      error_response(response.fetch(:errors))
    end
  end
end

The key point here is that this wiring does not contain any relevant logic that needs specific testing because it can be easily abstracted! Most of the time, connecting a function to an HTTP layer consists of the same steps:

Obtain the input data from the request.
Call a function with the obtained data.
Transform the output of the function into an HTTP response.

With this in mind, we could write a Ruby DSL to produce custom controllers, like this:

UsersController = Http.controller do
  action :login, ApiLogin, email: param(:email), password: param(:password)
end

And extend it as needed. For instance, we could implement header and json methods, analogous to param.

There are many ways to expose a function over HTTP. I personally like to build a pipeline of transformations where the input is the HTTP request and the output is the HTTP response, especially in functional languages with powerful type systems. This pipeline is defined safely and accurately step by step with a flexible API. I will write about how I did this in Haskell soon!

In conclusion, once we split logic from communication, we obtain some interesting benefits:

Our application logic becomes easier to use, understand and test.
The communication details can be centralized, changed and tested using a single-responsibility abstraction.
We can implement a new communication layer (a CLI, a different HTTP layer) to expose the same logic.

Let me know about your thoughts in the comments! Why do you think it's such a common issue? Are you already doing something similar?

Use opaque types in Elm!

Héctor Ramón — Sat, 27 Oct 2018 17:40:04 +0000

It's been a while since I joined the Elm Slack. During this time, I have seen different folks ask how, and when, to use opaque types. I have also seen many codebases and examples where opaque types were non-existent.

I think opaque types are extremely important when it comes to API design in Elm and I suspect they are not used nearly enough. In this article we will learn how opaque types can glue an API together while making our code self-documenting and bug-free.

A common scenario

We will work with an example of what I think is a fairly common scenario: a form that validates and submits some data to create a new resource remotely. This kind of interaction is the core of many interactive web applications.

For simplicity, we will assume the resource we want to create is a very simple question with a title and a body.

First, we will start with code that does not use any opaque types. Then, we will be gradually adding them and analyzing how code has improved along the way!

Let's begin!

An example with primitives

We want to create a question. Let's say we write a module Question with this API:

module Question exposing (create)

create : String -> String -> Task Http.Error String

This create function takes a question title and a body and returns a Task which tries to create the appropriate question. This Task can either fail and return an Http.Error, or succeed and return a String representing the slug of the brand new question.

Then, we build a form so our users can create questions. We will focus on the code that submits the form, leaving out some irrelevant details like how the fields are updated/rendered:

type alias Model =
    { title : String
    , body : String
--  , ...
    }

type Msg
    = Submit
    | QuestionCreated (Result Http.Error String)
--  | ...

update : Msg -> Model -> ( Model, Cmd Msg )
update msg model =
    case msg of
        Submit ->
            ( model
            , Question.create model.title model.body
                |> Task.attempt QuestionCreated
            )

        -- ...

view : Model -> Html Msg
view model =
    form
      [ onSubmit Submit ]
      [ titleField model
      , bodyField model
      , submitButton model
      ]

Do you notice any issues here? Let's see. What happens when we Submit our form? We create the question using Question.create. Sounds good! But wait... Where is validation?! What happens if model.title is empty? What if model.body is extremely long? Hmm... Okay, no problem. We just need to add an if-then-else, right?

case msg of
    Submit ->
        if Question.titleIsValid model.title && Question.bodyIsValid model.body then
            ( model
            , Question.create model.title model.body
                |> Task.attempt QuestionCreated
            )
        else
            ( model, Cmd.none )

    -- ...

Cool! We are done here. The new titleIsValid and bodyIsValid functions deal with validation and there is no way to create an invalid question now.

However, doesn't this feel a bit off? Whenever we want to use create we have to remember to validate its input by using titleIsValid and bodyIsValid. What if some requirements change and create needs another argument? We will have to remember to update the if-then-else. What if some new developer reads the type signature of create and decides to use it somewhere else without any kind of validation? Not desirable.

In the end, our API is error-prone. It can be used incorrectly. Can we do better? Wouldn't it be nice if we could somehow tie the concept of validating and creating a question together?

Opaque types to the rescue!

Before we continue, let's review what an opaque type is:

An opaque type is a custom type without exposed constructors.

Okay, but if the constructors are not exposed... How do we use an opaque type? Well, the constructors are accessible internally, in the module where the custom type has been defined. Therefore, we can expose functions to control how the values of the opaque type are created.

Let's see how this works! Going back to our Question module:

module Question exposing (create)

create : String -> String -> Task Http.Error String

The issue with create is that the types of its arguments accept invalid domain values. For instance, "" is a perfectly valid String but it is not a valid question title.

Can we create a new custom type where its possible values are always valid question titles? Let's see:

module Question exposing (Title, create, titleFromString)

type Title
    = Title String

titleFromString : String -> Result String Title
titleFromString title =
    if String.length title < 5 then
        Err "the title must not be less than 5 characters long"
    else if String.length title > 100 then
        Err "the title must not be more than 100 characters long"
    else
        Ok (Title title)

-- ...

That's it! Here we define a new custom type Title without exposing its constructor. Instead, we implement a titleFromString function which takes a String and returns either a String describing an error when validation fails, or a Title when validation succeeds.

The only way to build a Title is to use titleFromString. As a consequence, if we have a Title anywhere in our codebase, we can be confident that it is a valid question title. The Title type guarantees validity.

Whenever we are validating data, we are just checking that the data has some guarantees. Performing validation and then using the same type afterwards is a missed opportunity! We should try to capture these guarantees using opaque types. As a result, our APIs will become safer and easier to understand.

Similarly, we can define a Body type. Then, we can update the create function:

module Question exposing (Body, Title, create, bodyFromString, titleFromString)

-- type Title ...
-- type Body ...

create : Title -> Body -> Task Http.Error String

Now, the create function forces us to provide a valid title and a valid body. We cannot longer submit the form as we did before. We must use titleFromString and bodyFromString:

case msg of
    Submit ->
        case ( Question.titleFromString model.title, Question.bodyFromString model.body ) of
            ( Ok title, Ok body ) ->
                -- Validation succeded
                ( model
                , Question.create title body
                    |> Task.attempt QuestionCreated
                )

            _ ->
                -- Validation failed
                ( model, Cmd.none )

    -- ...

Our API does not provide any other way to do this. We cannot skip validation anymore! We do not even need to remember validation. The API forces us to deal with errors along the way. Our API is safer.

Further improvements

We are not done yet! There are still a couple of things we can improve.

The first improvement has to do with duplicated validation. We are currently performing validation in our update function when the form is submitted, but we probably want to validate the form fields in our view code too, maybe show error messages in real time. Therefore, update and view are both using titleFromString and bodyFromString: update only cares about the successful result, while view only cares about the errors.

Now that we have Title and Body types, we can make our Submit message impossible to be fired if the form values are invalid, validating only once in view and propagating the validation guarantees over to update. We just need to change the Submit message:

type Msg
    = Submit Question.Title Question.Body
    -- |...


case msg of
    Submit title body ->
        ( model
        , Question.create title body
            |> Task.attempt QuestionCreated
        )

    -- ...

Clean! We got rid of the awkward no-operation in the else clause when validation failed.

This particular approach, where form validation happens in view while capturing guarantees using opaque types, is one of the main ideas behind a package that I wrote: composable-form. composable-form treats forms as composable units, so they can be built, combined, and reused freely. I will write about it soon!

The second improvement is simple. We can create a Slug opaque type. Then, the create function will look even better:

create : Title -> Body -> Task Http.Error Slug

Now, if we ever need to allow our users to edit questions, we could just write an edit function:

edit : Slug -> Title -> Body -> Task Http.Error Slug

Neat! Our API will explicitly say a question can only be edited if it has been previously created.

In summary

Opaque types not only make your code safer, but they can also be used to connect different concepts together, making your codebase much easier to understand.

Here is one exercise I like to perform when I code: I try to imagine the thought process that a new developer, with a specific goal in mind, will have when reading the module documentation. Let's do that with our Question module, assuming Bob wants to find out how to create a new question:

Bob finds a create function.
Bob sees he can create a question if he provides a Title and a Body.
Bob wonders if there is some way to build these using a String.
Bob finds titleFromString and bodyFromString, which seem to do the job.
Bob notices those functions return a Result.
Bob understands he will need to handle the case where the provided String is not valid.

In this case, the developer can get a clear understanding of the Question API just by looking at the type signatures. No comments needed!

This is it for now! I will write more about Elm soon.

I would like to hear about your thoughts on opaque types and form validation, so do not hesitate to comment! You can also find me (@hecrj) in the Elm Slack, I am always happy to talk.