.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "pods::SDL::Tutorial::LunarLander 3pm"
.TH pods::SDL::Tutorial::LunarLander 3pm 2024-01-10 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SDL::Tutorial::LunarLander \- a small tutorial on Perl SDL
.SS CATEGORY
.IX Subsection "CATEGORY"
Tutorials
.SH INTRODUCTION
.IX Header "INTRODUCTION"
This is a quick introduction to Games, Perl, and  SDL (Simple 
DirectMedia Layer, a cross-platform multimedia programming 
library). We'll write a small game \-\- Lunar Lander \-\- in 100 
lines of code, or less.
.PP
\fICREATING A DEMO\fR
.IX Subsection "CREATING A DEMO"
.PP
You can see the final version of the demo code by doing:
.PP
.Vb 1
\&   perl \-MSDL::Tutorial::LunarLander=lander.pl \-e1
.Ve
.PP
this will create all three files used in the tutorial.
.SS "FIRST VERSION"
.IX Subsection "FIRST VERSION"
We'll start with a text version of the game.
.PP
"What?", you may ask. "I thought it was a SDL tutorial".
.PP
Yes, it is \-\- thank you for reminding me. But we'll leave the SDL part for
later. We must build the game logic first!
.PP
One of the traps of game programming is focusing too much on the interface.
If we start with a simpler simulation, we can worry with the presentation
later.
.PP
So, here's the initial code:
.PP
.Vb 1
\&    #!/usr/bin/perl
\&
\&    use strict;
\&    use warnings;
\&
\&    my $height   = 1000; # m
\&    my $velocity = 0;    # m/s
\&    my $gravity  = 1;    # m/s^2
\&
\&    my $t = 0;
\&
\&    while ( $height > 0 ) {
\&        print "at $t s height = $height m, velocity = $velocity m/s\en";
\&
\&        $height   = $height \- $velocity;
\&        $velocity = $velocity + $gravity;
\&        $t        = $t + 1;
\&    }
\&
\&    if ( $velocity > 10 ) {
\&        print "CRASH!!!\en";
\&    } else {
\&        print "You landed on the surface safely! :\-D\en";
\&    }
.Ve
.PP
Run the code and you'll see something like this:
.PP
.Vb 10
\&    at 0 s height = 1000 m, velocity = 0 m/s
\&    at 1 s height = 1000 m, velocity = 1 m/s
\&    at 2 s height = 999 m, velocity = 2 m/s
\&    at 3 s height = 997 m, velocity = 3 m/s
\&    at 4 s height = 994 m, velocity = 4 m/s
\&    at 5 s height = 990 m, velocity = 5 m/s
\&    ...
\&    at 43 s height = 97 m, velocity = 43 m/s
\&    at 44 s height = 54 m, velocity = 44 m/s
\&    at 45 s height = 10 m, velocity = 45 m/s
\&
\&    CRASH!!!
.Ve
.PP
"What happened? How do I control the ship???"
.SS "CONTROLLING THE SHIP"
.IX Subsection "CONTROLLING THE SHIP"
The problem with our first spaceship is that it had no controls!
.PP
So, let's fix this problem, making the spaceship scriptable. (We 
could write some code to handle keyboard and joysticks now, but 
an scriptable spaceship will be easier to start. Remember, focus
on the game logic!)
.PP
So, create add this simple script to the end of your file:
.PP
.Vb 6
\&    _\|_DATA_\|_
\&    at 41s, accelerate 10 m/s^2 up
\&    at 43s, 10 m/s^2
\&    at 45s, 10
\&    at 47s, 10
\&    at 49s, 10
.Ve
.PP
The script is straightforward: it simply states a time when we
will push the spaceship up with a given acceleration. It accepts
free text: any two numbers you type will work.
.PP
We can parse the script using this regular expression:
.PP
.Vb 1
\&    my $script_re = qr/(\ed+) \eD+ (\ed+)/x;
.Ve
.PP
And we can build a hash of ( time => acceleration ) with:
.PP
.Vb 1
\&    my %up = map { $_ =~ $script_re } <DATA>;
.Ve
.PP
So the middle section of the program will become:
.PP
.Vb 2
\&    my $script_re = qr/(\ed+) \eD+ (\ed+)/x;
\&    my %up = map { $_ =~ $script_re } <DATA>;
\&
\&    while ( $height > 0 ) {
\&        print "at $t s height = $height m, velocity = $velocity m/s\en";
\&
\&        if ( $up{$t} ) {
\&            my $a = $up{$t};
\&            print "(accelerating $a m/s^2)\en";
\&            $velocity = $velocity \- $a;
\&        }
\&
\&        $height   = $height \- $velocity;
\&        $velocity = $velocity + $gravity;
\&        $t        = $t + 1;
\&    }
.Ve
.PP
That's it!
.PP
Try to run the program, and the ship should land safely:
.PP
.Vb 12
\&    ./lunar.pl autopilot.txt 
\&    at 0 s height = 1000 m, velocity = 0 m/s
\&    at 1 s height = 1000 m, velocity = 1 m/s
\&    at 2 s height = 999 m, velocity = 2 m/s
\&    at 3 s height = 997 m, velocity = 3 m/s
\&    at 4 s height = 994 m, velocity = 4 m/s
\&    at 5 s height = 990 m, velocity = 5 m/s
\&    ...
\&    at 54 s height = 19 m, velocity = 4 m/s
\&    at 55 s height = 15 m, velocity = 5 m/s
\&    at 56 s height = 10 m, velocity = 6 m/s
\&    at 57 s height = 4 m, velocity = 7 m/s
\&
\&    You landed on the surface safely! :\-D
.Ve
.PP
Cool, but...
.SS "HOW ABOUT THE GRAPHICS?"
.IX Subsection "HOW ABOUT THE GRAPHICS?"
Okay, okay... now that we have a working prototype, we can work on
the graphics. But, first of all, we'll need...
.PP
\fITHE GRAPHICS\fR
.IX Subsection "THE GRAPHICS"
.PP
Yes, the graphics.
.PP
We won't use anything fancy here, just two images: a large one, for
the background, and a smaller one for the spaceship.
.PP
Create the images using the Gimp, or use the images provided by
this tutorial; Save these images in a subdirectory called "images":
("\f(CW\*(C`images/background.jpg\*(C'\fR" and "\f(CW\*(C`images/ship.png\*(C'\fR").
.SS "USING SDL"
.IX Subsection "USING SDL"
First step: use the required libraries:
.PP
.Vb 6
\&        use SDL; #needed to get all constants
\&        use SDL::Video;
\&        use SDLx::App;
\&        use SDL::Surface;
\&        use SDL::Rect;
\&        use SDL::Image;
.Ve
.PP
Second step: initialize \f(CW\*(C`SDLx::App\*(C'\fR:
.PP
.Vb 6
\&    my $app = SDLx::App\->new(
\&        title  => "Lunar Lander",
\&        width  => 800,
\&        height => 600,
\&        depth  => 32,
\&    );
.Ve
.PP
Third step: load the images and create the necessary "rectangles":
.PP
.Vb 2
\&        my $background = SDL::Image::load(\*(Aqimages/background.jpg\*(Aq);
\&        my $ship       = SDL::Image::load(\*(Aqimages/ship.jpg\*(Aq);
\&
\&        my $background_rect = SDL::Rect\->new(0,0,
\&            $background\->w,
\&            $background\->h,
\&        );
\&
\&        my $ship_rect = SDL::Rect\->new(0,0,
\&            $ship\->w,
\&            $ship\->h,
\&        );
.Ve
.PP
Fourth step: create a sub to draw the spaceship and background:
.PP
.Vb 2
\&        sub draw {
\&            my ( $x, $y ) = @_; # spaceship position
\&
\&            # fix $y for screen resolution
\&            $y = 450 * ( 1000 \- $y ) / 1000;
\&
\&            # background
\&            SDL::Video::blit_surface($background, $background_rect, $app, $background_rect );
\&
\&            # ship
\&            my $ship_dest_rect = SDL::Rect\->new(
\&                $x, $y, $ship\->w, $ship\->h,
\&            );
\&
\&            SDL::Video::blit_surface($ship, $ship_rect, $app, $ship_dest_rect );
\&
\&            SDL::Video::update_rects($app, $background_rect);
\&        }
.Ve
.PP
Note that this sub first combines all the bitmaps, using a blit
("Block Image Transfer") operation \-\- which is quite fast, but does
not update the display.
.PP
The combined image is displayed in the last line. This process of
combining first, and displaying later, avoids that annoying fading
between cycles ("flickering").
.PP
Finally, add the following lines to the end of the main loop, so that
we call the \f(CWdraw()\fR function with the correct spaceship
coordinates:
.PP
.Vb 1
\&    while ( $height > 0 ) {
\&
\&        # ...
\&
\&        draw( 100, $height );
\&        $app\->delay(10);
\&    }
.Ve
.PP
That's it!
.PP
Run the program and watch the spaceship landing safely on the surface
of the moon.
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2009 Nelson Ferraz, all rights reserved.
.PP
Updated and maintained by the SDL Perl project. See "AUTHORS" in SDL.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.