Coleman-Code/COM380/Project5/GambleKit/Intruduction.txt

This is the first publicly released version of the Kit and its documentation is still scarcely written.

1. GambleKit's ideology

	GambleKit aims at a declarative style of programming gambling games, and especially slot machine simulations. 
	The basic idea and guiding point is to emphasize on the declarative nature of the api, so that much coding and tedious work is saved by declaring the entities and models of the game, most often at its initialization, on game pages' creation.
	As at creation time the environment is still relatively static, logic should be more plainly covered and readable after time, plus this greatly reduces the per-frame code, leaving mostly the higher level operations.
	Because resources for woring on the kit are scarce, access to most, if not all parts of the entities is also provided. This leaves the ability to make custom changes at runtime and modify the parts of the game if required.
	Just as any real-time rendering application, a game which uses GambleKit will need to process its entities at every frame. Aside from the declarations, the per-frame code is the second half of the general programing of a game with the kit.


2. Organization
	The object, which is highest in a game's logic is an instance of the "GkGame" class. It manages all the game's screens, or "pages", and handles loading of resources. Normally, there would be one such object.
	GambleKit is organized into "pages". That is because a game may have different screens, each with separate logic - for example a main screen with reels, or one with a bonus, or a menu, or whatever. These screens are represented by pages - instances of the GkGamePage class. Each page has its own visual and logical layout, and how one page is built does not affect another. Only one page can be rendered at a time.
	Each page is constructed out of Entities. Entities are, in most part, visual objects like animated images, texts, buttons, reels. An entity can also be not visible - one such are the bindings. Basically, the entities are what constructs most, if not all of a page. The whole game might be constructed entirely of them by adding them to their page in the correct manner. A game page automatically handles the behaviour of its entities and they might run fairly well without any intervention from the programmer, aside from declaring them.
	
	Loading of resources is handled by the GkGame object. Each page of the game can and should separately load whatever resources it needs, regardless of other pages. The resources manager of GkGame handles the loading and prevents for doubling resources in memory. This way, a page is added or removed from GkGame and the exactly the right resources will be loaded with no overweight and no resource misses. Simply load in every page exactly and only what it requires. Releasing of the resources is automatically done when the GkGame object is destroyed.
	There are a few methods for loading resources. Among their parameters, two can always be found: a "fileName" and a "virtualFileName". Because GambleKit can load its resources from a virtual file system contained in a single file, "fileName" is the name of the file containing the virtual file system. "virtualFileName" is the name to the actual file resource - either in the virtual file system, or in the real one, depending on how the file system management is set.
		"AcquireAnimatedTexture" method loads a single image file and depending on the given parameters, may split it into pieces to form an animation
		"AcquireAnimatedTextureFromMultipleFiles" method loads a number of image files, making animation out of each of them. The name of the files should be formatted with a five-digit index, giving the frame number, say "image_00000.png", "image_00001.png", "image_00002.png" and so on. With the latter example, the "virtualFileName" parameter should be given as "image_{0}.png", where the {0} denotes where the index is.
		"AcquireAnimatedFontFromMultipleFiles" method loads an animated font. Like "AcquireAnimatedTextureFromMultipleFiles", it loads multiple images in the same manner, but it uses each image as a letter for the font, while the "numFrames" parameter determines in how many pieces, or frames, to split each image to animate it.
		"AcquireSoundSource" method loads a single sound file in the raw PCM wav format and creates a sound source, which can be played.

3. Entities
	Entities will be described in a later release. I am lone, tired and hungry, so please forgive my lack of will for now.

4. Demonstration code
	Starting with "main.cpp" we have a standart entry point for the application. Some debug memory leak detection enabling, some initializers and then the mainWindow and the loop processing it.
	Looking at the "MainWindow" class, there is its constructor, where a GkGraphicsDevice, a GkSoundDevice and a CustomGame objects are created. There is the MainLoop, where every frame is processed and rendered. There are the MouseDown and MouseUp method, where mouse events are fetched to the game object. And there are some other minor routines. The GkWindowsForm class GKDLLCLASS have a couple of methods which can be overridden when appropriate. The most interesting part here is the creation of CustomGame, which is, after all, the game.
	In "CustomGame" class GKDLLCLASS there is not much code to behold - creation of a log and then the addition of a new GkGamePage - the "MainPage" to the game.
	Finally, having a grasp of some real-deal code in the "MainPage" class, there's the actual difinition of the entities of the page in its constructor and some actual per-frame custom processing in its "Process" method.
		In the constructor, the page is build through its "AddEntity" method which, just as its name promises, adds a GkGameEntity object to the page, and returns it so that it can eventually comfortably be assigned to a variable if needed. Most of the entities' constructors have many parameters with default values in order be easier to declare and add in one line. The buttons for example may not have only one or two animations for faces, while a GkGameAnimation's constructor may be given paramters such that flip the image, stretch it, override the animation framerate, make it inactive of invisible.
		The page's "Process" method is called before the rendering of every frame. It is a convenient place to perform real-time routines, implement custom logic and program some additional dynamic to the game page. Here, the buttons are handled in regard to the motional state of the reels. Buttons are created with such parameters, that automatically renders them inactive, if their state was not asked for, which is why no logic has to be implemented for this task. Even though the "credits" member variable is changed instantly, the text for credits changes smoothly, because it was bound to a GkGameWinningCounter counter entity.