What this tells us is that to get started we need:

• [ ] A ggez Context
• [ ] A ggez EventsLoop
• [ ] A struct that implements EventHandler

We can actually make a Context and EventsLoop with a single step, so let's get that out of the way. Clear your main method and add this:

fn main() {
   let (ctx, event_loop) = &mut ggez::ContextBuilder::new("Pong", "Mikail Khan").build();
}

ggez nicely comes with a ContextBuilder to make a Context and EventsLoop. This is an example of the builder pattern in Rust.

ggez::ContextBuilder::new("Pong", "Mikail Khan") creates a ContextBuilder with title "Pong" and author "Mikail Khan". Running .build() on it creates a Context and EventsLoop. The &mut at the front makes sure that we get a mutable reference to the created values.

Next, we need a struct that implements ggez::event::EventHandler. For convenience, add use ggez::event::EventHandler to the start of the file. Next, make a struct MainState. It doesn't need to have anything for now.

struct MainState {
}

Next, we need to implement EventHandler for MainState. EventHandler is the trait that lets ggez know what to do with your struct to get the game going. It sets up the main loop and the draw loop for your game.

impl EventHandler for MainState {
}

If you run cargo check (or cargo build) now, you'll get an error:

error[E0046]: not all trait items implemented, missing: `update`, `draw`
  --> src/main.rs:20:1
   |
20 | impl EventHandler for MainState {
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ missing `update`, `draw` in implementation
   |
   = help: implement the missing item: `fn update(&mut self, _: &mut ggez::context::Context) -> std::result::Result<(), ggez::error::GameError> {
 todo!() }`
   = help: implement the missing item: `fn draw(&mut self, _: &mut ggez::context::Context) -> std::result::Result<(), ggez::error::GameError> { t
odo!() }`

This error tells us that we're missing two functions and gives us their signatures. If we follow its advice, we get:

impl EventHandler for MainState {
  fn update(&mut self, ctx: &mut ggez::Context) -> ggez::GameResult {
    todo!()
  }

  fn draw(&mut self, ctx: &mut ggez::Context) -> ggez::GameResult {
    todo!()
  }
}

todo!() is a macro which just exits the program with an error.

Now that we have the skeleton of a struct that implements EventHandler, we can complete our main method for now:

fn main() {
  // create a mutable reference to a `Context` and `EventsLoop`
  let (ctx, event_loop) = &mut ggez::ContextBuilder::new("Pong", "Fish").build().unwrap();

  // Make a mutable reference to `MainState`
  let main_state = &mut MainState {};

  // Start the game
  ggez::event::run(ctx, event_loop, main_state);
}

The program is now runnable! It doesn't do anything yet though. We get this error:

thread 'main' panicked at 'not yet implemented', src/main.rs:22:9
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

That's because ggez tried to run our update() method, which just has a todo!().

There's also one warning:

warning: unused `std::result::Result` that must be used
  --> src/main.rs:38:5
   |
38 |   ggez::event::run(ctx, event_loop, main_state);
   |   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
   = note: `#[warn(unused_must_use)]` on by default
   = note: this `Result` may be an `Err` variant, which should be handled

This error tels us that ggez::event::run returns a Result, which might be an error. If it's an error, we should handle it. However, if this function fails, the program can't really recover. Also, it's going to be the last line in main(). To fix this, we can make main() return a Result. This is useful because if main() fails the error will just be printed when the program crashes. ggez::event::run() specifically returns a ggez::GameResult, so that's what we should make main() return.

Change the function signature to

fn main() -> ggez::GameResult

If we try to compile this (or cargo check it), we'll get another error:

error[E0308]: mismatched types
  --> src/main.rs:30:14
   |
30 | fn main() -> ggez::GameResult {
   |  ----    ^^^^^^^^^^^^^^^^ expected enum `std::result::Result`, found `()`
   |  |
   |  implicitly returns `()` as its body has no tail or `return` expression
...
38 |   ggez::event::run(ctx, event_loop, main_state);
   |                          - help: consider removing this semicolon
   |
   = note:   expected enum `std::result::Result<(), ggez::error::GameError>`
       found unit type `()`

error: aborting due to previous error

For more information about this error, try `rustc --explain E0308`.

The Rust compiler helpfully tells us exactly what to do. If we remove the last semicolon on our ggez::event::run() call, main() will return it. Now, main() looks like this:

fn main() -> ggez::GameResult {
  // create a mutable reference to a `Context` and `EventsLoop`
  let (ctx, event_loop) = &mut ggez::ContextBuilder::new("Pong", "Fish").build().unwrap();

  // Make a mutable reference to `MainState`
  let main_state = &mut MainState {};

  // Start the game
  ggez::event::run(ctx, event_loop, main_state)
}

To stop the game from crashing immediately, we should replace the bodies of our update() and draw() functions with something other than todo!(). Since both of them also return a Result, we can make both of them just return Ok(()), which just means that there's been no errors.

impl EventHandler for MainState {
  fn update(&mut self, _: &mut ggez::Context) -> ggez::GameResult {
    Ok(())
  }

  fn draw(&mut self, _: &mut ggez::Context) -> ggez::GameResult {
    Ok(())
  }
}

Running the program now will create a blank window and do nothing. That's the start of the game!

You can find the full code so far on Github here.

If you have any feedback, please email me at [email protected]

I'll write Part 2 soon and link it here.

Part 2: https://mkhan45.github.io/2020/05/20/Pong-tutorial-with-ggez-Part-2.html