timy created page: quickstart

quickstart.md

@@ -0,0 +1,68 @@
+# Quick-Start
+## Adding a Reference
+In your project (make a new project if you do not have one already), right-click “References” in the “Solution Explorer” and “Add Reference.” Go down to “Browse” and find the SpriteLibrary DLL. If you have built it (see above), it should be in your projects/SpriteLibrary/SpriteLibrary/Bin/Release directory. If you develop a game and use the built-in ClickOnce installer, this DLL will be automatically installed, along with your package, now that you have added it as a reference. So you should only need to do this once per project.
+
+## Using the Sprite Library
+You need to add a “using SpriteLibrary;” at the top of your main form, and in any code file (class, form, etc) where you reference the pieces of the Sprite Library (the Sprites, the SpriteController, etc.)
+
+## Initializing the Sprite Library
+In the form that you want to use for a game, you will want to create a SpriteController. You will need to define it first as a variable. Something like:
+```c#
+SpriteController MySpriteController;
+```
+You may notice that we do not yet instantiate it. We need to have a PictureBox associated with the SpriteController when we make it. So, after the form is loaded and the InitializeComponents(); has been run, then we can instantiate the SpriteController. In this example, we have a PictureBox named MainDrawingArea. You can have multiple sprite controllers per game, but you only want to have one per PictureBox. So you will want to store the variable, and pass it to the appropriate places that your program needs.
+```c#
+MainDrawingArea.BackgroundImageLayout = ImageLayout.Stretch;
+MySpriteController = new SpriteController(MainDrawingArea);
+```
+We set the background layout to stretch. This is important for being able to resize the window and for a number of other things.  If your sprite controller is not working from the very get-go, verify that the BackgroundLayout is set to stretch.
+
+## Adding your First Sprite
+First, you must have a sprite to add. Sprites are basically a series of frames on one image. Each frame is one picture, and is the same size (for example, 100x100). And there may be many frames in the image. The resulting image might be 400 x 100, or 200 x 200. The sprite will display each frame, one at a time. So you might have an image of your main character standing there. The next frame will be with his leg slightly extended. The next has his leg out. When we see it animate, the leg moves out as if your adventurer is walking. This sprite controller assumes the image will already have the transparency set so you can see the background behind the sprite, which basically means you are using png files with transparency.
+
+There are a few ways to create your sprite and load an animation. My example programs, which you can download from the URL at the top of this document, have us reading in the sprite from a sprite-sheet in the project resources.  But they can be loaded in from any image. The reason I use resource files is because the resource files are included along with the package in the click-once deployment. So it is a good place to put them if you are hoping to give your project to someone else. Loading a sprite looks something like this:
+```c#
+Sprite JellyMonster = new Sprite(new Point(0, 100), MySpriteController, 
+			Properties.Resources.monsters, 100, 100, 200, 4);
+
+JellyMonster.SetName(“jelly”);
+```
+In this example, we are making a sprite named JellyMonster by pulling the animation out of the second row of the image “Properties.Resources.monsters”. (0,0 is the first row, 0,100 is the second row.) We pass it the sprite controller, and then the “monsters” image file. We specify that the image we are pulling out is of the size 100 x 100. We use an animation speed of 200ms per frame, and we pull 4 frames out of the image. When we print the sprite, we can grow, or shrink the sprite on the PictureBox. It does not need to remain at 100x100. That is just the size of the individual frame in the sprite sheet image.
+
+The last step we do in the above code is to name the sprite. We name our master sprites, and then clone them when we want to have a bunch of them. We usually will not have the named sprites display on the screen without cloning (though you can). The main reason we do this is so that we can destroy sprites at our leisure, and make as many of them again whenever we want. When you destroy a clone, it is easy to make more from the master. But destroying the master means you need to start from scratch. It is very efficient to clone sprites, but it takes a lot more effort to generate new ones from scratch.
+You clone a sprite by doing something like: 
+```c#
+Sprite newsprite = SpriteController.DuplicateSprite(“spritename”);
+```
+
+## Telling Your Sprite To Do Something
+Now that we have a sprite, we can put it somewhere. Once it is placed on the background, it will automatically start displaying the first animation (animation 0). An animation is a series of pictures which the sprite displayer shows one after the other to make it look like it is walking, running, etc.  You can have multiple animations for each sprite (walk left, walk right, fall left, fall right, die, etc.) These animations are referenced by number.  This number is made in the order of which you added the animations to the sprite.  You can tell a sprite to change animations, or to animate once (leaving the sprite displaying the final frame of the animation). Here is some code for how the Sprite is configured in the ShootingDemo.
+```c#
+JellyMonster.AutomaticallyMoves = true;
+JellyMonster.CannotMoveOutsideBox = true;
+JellyMonster.SpriteHitsPictureBox += SpriteBounces;
+JellyMonster.SetSpriteDirectionDegrees(180);
+JellyMonster.PutBaseImageLocation(new Point(startx, starty));
+JellyMonster.MovementSpeed = 30;
+```
+We tell the Sprite that it will automatically move. We tell it that it cannot go outside the bounds of the picturebox. And then we tell it where it starts, and which direction it moves. The += line is an event. SpriteBounces is a function that gets executed when the Sprite hits the PictureBox. (See "Sprite Events" below).
+
+## Sprite Events
+You can add events to sprites. An event is a C# term.  You can google for “C# events” to understand more about them.  An event is triggered from some outside (or inside) force, and, when that event happens, the code on the event gets executed.
+
+For example, you can add some code that is run when one sprite hits another sprite. In the ShootingDemo, we add that event to the monster sprites. Many times a second, the sprites check to see if they have hit another sprite, and if they do, they execute the code in that event. There are events for when sprites hit the edge of the PictureBox, or if they have exited the picturebox. There is even an event that fires off before a sprite moves to a new location. You can use that one to adjust, or cancel the movement location.
+
+You need to create an event, and add that event to the sprite. Events are cloned with the sprites, so you can add events to the parent Sprite, and those events will work for all the cloned sprites.
+
+## Payload
+Each sprite has a payload that is of an empty class, “SpritePayload.” This means you can store virtually anything there. This is in case you want to add extra attributes to your sprites. If you want to track the health of different sprites, some attributes for the sprite AI, or other things, you can create a class and store that data in the Sprite.payload. You will want to make a class that overrides the SpritePayload that contains the values you want to store:
+```c#
+public class MonsterPayload : SpriteLibrary.SpritePayload
+    {
+        public int Health = 1;
+    }
+```
+You then make a new payload, set the data, and store it in the Sprite.payload.  If you have multiple types of payload in different sprites, you may want to verify that the sprite payload is the type you are expecting before you try to use it.
+```c#
+If(mySprite.payload != null && mySprite.payload is MonsterPayload) { dosomething;}
+```