Skip to content
Newer
Older
100644 1008 lines (784 sloc) 42.9 KB
7ac9722 @ippa first commit
authored
1 = CHINGU
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
2 http://github.com/ippa/chingu/tree/master
3
dec2095 @ippa readme
authored
4 DOCUMENTATION: http://rdoc.info/projects/ippa/chingu
5
3b938a8 readme updates and fixes
ippa authored
6 Ruby 1.9.2 is recommended. Should also work with 1.8.7+.
d85fa8e readme updates/fixes
ippa authored
7 Chingu development is mostly conducted using Win7 / Ruby 1.9.2.
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
8
7ac9722 @ippa first commit
authored
9
10 == DESCRIPTION
9d2d0c2 @ippa New Chingu tagline. Updated and fixes for docs across the whole lib. …
authored
11 OpenGL accelerated 2D game framework for Ruby.
12 Builds on the awesome Gosu (Ruby/C++) which provides all the core functionality.
3d68151 README updates and fixes to reflect on recent changes
ippa authored
13 It adds simple yet powerful game states, pretty input handling, deployment safe asset-handling, a basic re-usable game object and automation of common task.
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
14
7ac9722 @ippa first commit
authored
15
f4a2318 mention examples in readme
ippa authored
16 == INSTALL
17 gem install chingu
18
19
20 == QUICK START (TRY OUT THE EXAMPLES)
21 Chingu comes with 25+ examples demonstrating various parts of Chingu.
22 Please browse the examples-directory in the Chingu root directory.
23 The examples start out very simple. Watch out for instructions in the windows titlebar.
24 Could be how to move the onscreen player or how to move the example forward. Usually it's arrowkeys and space.
25 There's also more complex examples, like a clone of Conways game of life (http://en.wikipedia.org/wiki/Conway%27s_Game_of_Life) game_of_life.rb and example21_sidescroller_with_edit.rb where You can switch between playing and editing the level itself.
26
83a8311 added 'Projects using chingu' in README. Examples rock when learning …
ippa authored
27 == PROJECTS USING CHINGU
28 Links to some of the projects using/depending on Chingu:
a6f2072 add project using chingu + mention parallax/viewport problem in readme
ippa authored
29 * https://github.com/Spooner/wrath (pixely 2-player action adventure in development)
0926dba added 2 new projects (ludumdare entries) using chingu in readme
ippa authored
30 * http://ippa.se/games/unexpected_outcome.zip (LD#19 game compo entry by ippa)
31 * https://bitbucket.org/philomory/ld19/ (LD#19 game compo entry by philomory)
5e317bb fix formatting in 'projects using chingu' list in readme once and for…
ippa authored
32 * https://github.com/Spooner/fidgit (GUI-lib )
33 * https://github.com/Spooner/sidney (Sleep Is Death remake in ruby)
34 * https://github.com/ippa/the_light_at_the_end_of_the_tunnel (LD#16 game compo entry)
35 * https://github.com/ippa/gnorf (LD#18 game compo entry. Decent minigame with online highscores.)
36 * https://github.com/ippa/holiday_droid (Work in progess platformer)
37 * https://github.com/ippa/pixel_pang (Work in progress remake of the classic Pang)
38 * https://github.com/ippa/whygone (An odd little platformer-puzzle-game for _why day)
39 * https://github.com/erisdiscord/gosu-tmx (a TMX map loader)
40 * https://github.com/rkachowski/tmxtilemap (Another TMX-class)
41 * https://github.com/erisdiscord/gosu-ring (Secret of Mana-style ring menu for chingu/gosu)
42 * https://github.com/deps/Berzerk (remake of the classic game. comes with robots.)
43 * https://github.com/rkachowski/tigjamuk10 ("sillyness from tigjamuk - CB2 bistro in Cambridge, January 2010")
44 * https://github.com/zukunftsalick/ruby-raid (Remake of Ataris river raid, unsure of status)
45 * https://github.com/edward/spacewar (a small game, unsure of status)
46 * https://github.com/jstorimer/zig-zag (2D scrolling game, unsure of status)
83a8311 added 'Projects using chingu' in README. Examples rock when learning …
ippa authored
47
f4a2318 mention examples in readme
ippa authored
48 ... miss your Chingu project? Msg me on github and I'll add it to the list!
83a8311 added 'Projects using chingu' in README. Examples rock when learning …
ippa authored
49
7ac9722 @ippa first commit
authored
50 == THE STORY
5c7b343 @ippa README.rdoc update and spellfixes
authored
51 The last years I've dabbled around a lot with game development.
7ac9722 @ippa first commit
authored
52 I've developed games in both Rubygame and Gosu. I've looked at gamebox.
5c7b343 @ippa README.rdoc update and spellfixes
authored
53 Rubygame is a very capable framework with a lot of functionality (collision detection, very good event system etc). Gosu is way more minimalistic but also faster with OpenGL -acceleration. Gosu isn't likely to get much more complex since it does what it should do very well and fast.
7ac9722 @ippa first commit
authored
54
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
55 After 10+ game prototypes and some finished smaller games I started to see patterns each time I started a new game. Making classes with x/y/image/other-parameters that I called update/draw on in the main loop.
56 This became the basic Chingu::GameObject which encapsulates Gosus "Image.draw_rot" and enables automatic updating/drawing through "game_objects".
7ac9722 @ippa first commit
authored
57
5c7b343 @ippa README.rdoc update and spellfixes
authored
58 There was always a huge big chunk of checking keyboard-events in the main loop.
59 Borrowing ideas from Rubygame this has now become @player.keyboard(:left => :move_left, :space => :fire ... etc.
7ac9722 @ippa first commit
authored
60
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
61
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
62 == CORE OVERVIEW
63 Chingu consists of the following core classes / concepts:
7ac9722 @ippa first commit
authored
64
5c7b343 @ippa README.rdoc update and spellfixes
authored
65 === Chingu::Window
3d68151 README updates and fixes to reflect on recent changes
ippa authored
66 The main window, use it at you use Gosu::Window now. Calculates the framerate, takes care of states,
36f1d24 readme fixes
unknown authored
67 handles chingu-formated input, updates and draws BasicGameObject / GameObjects automatically.
68 Available throughout your source as $window (Yes, that's the only global Chingu has).
3d68151 README updates and fixes to reflect on recent changes
ippa authored
69 You can also set various global settings. For example, self.factor=3, will make all fortcomming GameObjects scale 3 times.
5c7b343 @ippa README.rdoc update and spellfixes
authored
70
71 === Chingu::GameObject
cf2b3c2 @ippa components -> traits. everything now works with 1.8.7 and 1.9.1. vari…
authored
72 Use this for all your in game objects. The player, the enemies, the bullets, the powerups, the loot laying around.
3e1d67d @ippa readme updates + release github gem 0.3.0
authored
73 It's very reusable and doesn't contain any game-logic (that's up to you!). Only stuff to put it on screen a certain way.
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
74 If you do GameObject.create() instead of new() Chingu will keep save the object in the "game_object"-list for automatic updates/draws.
75 GameObjects also have the nicer Chingu input-mapping: @player.input = { :left => :move_left, :right => :move_right, :space => :fire}
76 Has either Chingu::Window or a Chingu::GameState as "parent".
5c7b343 @ippa README.rdoc update and spellfixes
authored
77
cf2b3c2 @ippa components -> traits. everything now works with 1.8.7 and 1.9.1. vari…
authored
78 === Chingu::BasicGameObject
79 For those who think GameObject is a too little fat, there's BasicGameObject (GameObject inherits from BasicGameObject).
80 BasicGameObject is just an empty frame (no x,y,image accessors or draw-logic) for you to build on.
36f1d24 readme fixes
unknown authored
81 It _can_ be extended with Chingus trait-system though. The new() vs create() behavior of GameObject comes from BasicGameObject.
82 BasicGameObject#parent points to either $window or a game state and is automatically set on creation time.
3e1d67d @ippa readme updates + release github gem 0.3.0
authored
83
84 === Chingu::GameStateManager
85 Keeps track of the game states. Implements a stack-based system with push_game_state and pop_game_state.
5c7b343 @ippa README.rdoc update and spellfixes
authored
86
87 === Chingu::GameState
3e1d67d @ippa readme updates + release github gem 0.3.0
authored
88 A "standalone game loop" that can be activated and deactivated to control game flow.
89 A game state is very much like a main gosu window. You define update() and draw() in a gamestate.
90 It comes with 2 extras that main window doesn't have. #setup (called when activated) and #finalize (called when deactivated)
91
92 If using game states, the flow of draw/update/button_up/button_down is:
93 Chingu::Window --> Chingu::GameStateManager --> Chingu::GameState.
94 For example, inside game state Menu you call push_game_state(Level). When Level exists, it will go back to Menu.
7ac9722 @ippa first commit
authored
95
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
96 === Traits
3d68151 README updates and fixes to reflect on recent changes
ippa authored
97 Traits are extensions (or plugins if you so will) to BasicGameObjects included on the class-level.
36f1d24 readme fixes
unknown authored
98 The aim is so encapsulate common behavior into modules for easy inclusion in your game classes.
76d78c0 @ippa draw/update in traits are now draw_trait/update_trait. Make Chingu au…
authored
99 Making a trait is easy, just an ordinary module with the methods setup_trait(), update_trait() and/or draw_trait().
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
100 It currently has to be namespaced to Chingu::Traits for "traits" to work inside GameObject-classes.
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
101
102 == OTHER CLASSES / HELPERS
103
104 === Chingu::Text
ff48b59 @ippa more readme updates, mention HighScoreList
authored
105 Makes use of Image#from_text more rubyish and powerful.
106 In it's core, another Chingu::GameObject + image genning with Image#from_text.
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
107
cf2b3c2 @ippa components -> traits. everything now works with 1.8.7 and 1.9.1. vari…
authored
108 === Chingu::Animation
109 Load and interact with tile-based animations. loop, bounce and access invidual frame(s) easily.
ff48b59 @ippa more readme updates, mention HighScoreList
authored
110 An "@image = @animation.next" in your Player#update is usually enough to get you started!
cf2b3c2 @ippa components -> traits. everything now works with 1.8.7 and 1.9.1. vari…
authored
111
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
112 === Chingu::Parallax
ff48b59 @ippa more readme updates, mention HighScoreList
authored
113 A class for easy parallaxscrolling. Add layers with different damping, move the camera to generate a new snapshot. See example3.rb for more.
a6f2072 add project using chingu + mention parallax/viewport problem in readme
ippa authored
114 NOTE: Doing Parallax.create when using a trait viewport will give bad results.
115 If you need parallax together with viewport do Parallax.new and then manually doing parallax.update/draw.
ff48b59 @ippa more readme updates, mention HighScoreList
authored
116
117 === Chingu::HighScoreList
118 A class to keep track of high scores, limit the list, automatic sorting on score, save/load to disc. See example13.rb for more.
7ac9722 @ippa first commit
authored
119
d85fa8e readme updates/fixes
ippa authored
120 === Chingu::OnlineHighScoreList
121 A class to keep/sync online highscores to http://gamercv.com/. A lot more fun competing with others for positions then a local list.
122
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
123 === Various Helpers
124 Both $window and game states gets some new graphical helpers, currently only 3, but quite useful:
125
55692d2 @ippa readme formating
authored
126 fill() # Fills whole window with color 'color'.
127 fill_rect() # Fills a given Rect 'rect' with Color 'color'
128 fill_gradient() # Fills window or a given rect with a gradient between two colors.
0a8e0f5 @ippa README additions
authored
129 draw_circle() # Draws a circle
130 draw_rect() # Draws a rect
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
131
132 If you base your models on GameObject (or BasicGameObject) you get:
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
133 Enemy.all # Returns an Array of all Enemy-instances
134 Enemy.size # Returns the amount of Enemy-instances
135 Enemy.destroy_all # Destroys all Enemy-instances
136 Enemy.destroy_if(&block) # Destroy all objects for which &block returns true
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
137
138
139 == BASICS / EXAMPLES
179ae00 @ippa readme updates, examples etc
authored
140
700c950 @ippa big README update
authored
141 === Chingu::Window
5c7b343 @ippa README.rdoc update and spellfixes
authored
142 With Gosu the main window inherits from Gosu::Window. In Chingu we use Chingu::Window. It's a basic Gosu::Window with extra cheese on top of it. keyboard handling, automatic update/draw calls to all gameobjects, fps counting etc.
700c950 @ippa big README update
authored
143
179ae00 @ippa readme updates, examples etc
authored
144 You're probably familiar with this very common Gosu pattern:
145
146 ROOT_PATH = File.dirname(File.expand_path(__FILE__))
147 class Game < Gosu::Window
148 def initialize
149 @player = Player.new
150 end
151
152 def update
153 if button_down? Button::KbLeft
0bbf047 @ippa more docs
authored
154 @player.left
155 elsif button_down? Button::KbRight
156 @player.right
157 end
158
179ae00 @ippa readme updates, examples etc
authored
159 @player.update
160 end
161
162 def draw
163 @player.draw
164 end
165 end
166
167 class Player
168 attr_accessor :x,:y,:image
169 def initialize(options)
170 @x = options[:x]
171 @y = options[:y]
172 @image = Image.new(File.join(ROOT_PATH, "media", "player.png"))
173 end
174
175 def move_left
176 @x -= 1
177 end
178
179 def move_right
180 @x += 1
181 end
182
183 def draw
184 @image.draw(@x,@y,100)
185 end
186 end
187
188 Game.new.show # Start the Game update/draw loop!
189
190
d169eb1 various readme updates
ippa authored
191 Chingu doesn't change the fundamental concept/flow of Gosu, but it will make the above code shorter:
179ae00 @ippa readme updates, examples etc
authored
192
193 #
194 # We use Chingu::Window instead of Gosu::Window
195 #
cfa1e45 @jduff little fix to one ofthe examples in the docs, a bunch of spelling
jduff authored
196 class Game < Chingu::Window
179ae00 @ippa readme updates, examples etc
authored
197 def initialize
3d68151 README updates and fixes to reflect on recent changes
ippa authored
198 super # This is always needed if you override Window#initialize
179ae00 @ippa readme updates, examples etc
authored
199 #
36f1d24 readme fixes
unknown authored
200 # Player will automatically be updated and drawn since it's a Chingu::GameObject
f9fd433 @ippa Various README updates, biggest beeing a description of the execution…
authored
201 # You'll need your own Chingu::Window#update and Chingu::Window#draw after a while, but just put #super there and Chingu can do its thing.
179ae00 @ippa readme updates, examples etc
authored
202 #
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
203 @player = Player.create
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
204 @player.input = {:left => :move_left, :right => :move_right}
179ae00 @ippa readme updates, examples etc
authored
205 end
206 end
207
208 #
4ff81f3 @ippa Actor -> GameObject for our minimal abstract gameclass. save Actor-na…
authored
209 # If we create classes from Chingu::GameObject we get stuff for free.
f9fd433 @ippa Various README updates, biggest beeing a description of the execution…
authored
210 # The accessors image,x,y,zorder,angle,factor_x,factor_y,center_x,center_y,mode,alpha.
211 # We also get a default #draw which draws the image to screen with the parameters listed above.
5c7b343 @ippa README.rdoc update and spellfixes
authored
212 # You might recognize those from #draw_rot - http://www.libgosu.org/rdoc/classes/Gosu/Image.html#M000023
d169eb1 various readme updates
ippa authored
213 # And in it's core, that's what Chingu::GameObject is, an encapsulation of draw_rot with some extras.
5c7b343 @ippa README.rdoc update and spellfixes
authored
214 # For example, we get automatic calls to draw/update with Chingu::GameObject, which usually is what you want.
179ae00 @ippa readme updates, examples etc
authored
215 # You could stop this by doing: @player = Player.new(:draw => false, :update => false)
216 #
4ff81f3 @ippa Actor -> GameObject for our minimal abstract gameclass. save Actor-na…
authored
217 class Player < Chingu::GameObject
179ae00 @ippa readme updates, examples etc
authored
218 def initialize(options)
219 super(options.merge(:image => Image["player.png"])
220 end
221
222 def move_left
223 @x -= 1
224 end
225
226 def move_right
227 @x += 1
228 end
229 end
230
231 Game.new.show # Start the Game update/draw loop!
232
0bbf047 @ippa more docs
authored
233 Roughly 50 lines became 26 more powerful lines. (you can do @player.angle = 100 for example)
179ae00 @ippa readme updates, examples etc
authored
234
dec2095 @ippa readme
authored
235 If you've worked with Gosu for a while you're probably tired of passing around the window-parameter.
700c950 @ippa big README update
authored
236 Chingu solves this (as has many other developers) with a global variable $window. Yes, globals are bad, but in this case it kinda makes sense. It's used under the hood in various places.
237
f9fd433 @ippa Various README updates, biggest beeing a description of the execution…
authored
238 The basic flow of Chingu::Window once show() is called is this (this is called one game iteration or game loop):
239
240 - Chingu::Window#draw() is called
241 -- draw() is called on game objects belonging to Chingu::Window
242 -- draw() is called on all game objects belonging to current game state
243
244 - Chingu::Window#update() is called
245 -- Input for Chingu::Window is processed
246 -- Input for all game objects belonging to Chingu::Window is processed
247 -- update() is called on all game objects belonging to Chingu::Window
248 -- Input for current game state is processed
249 -- Input for game objects belonging to current game state is processed
250 -- update() is called on all game objects belonging to current game state
251
252 ... the above is repeatet until game exists.
253
4ff81f3 @ippa Actor -> GameObject for our minimal abstract gameclass. save Actor-na…
authored
254 === Chingu::GameObject
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
255 This is our basic "game unit"-class, meaning most in game objects (players, enemies, bullets etc) should be inherited from Chingu::GameObject.
256 The basic ideas behind it are:
700c950 @ippa big README update
authored
257
5c7b343 @ippa README.rdoc update and spellfixes
authored
258 * Encapsulate only the very common basics that Most in game objects need
259 * Keep naming close to Gosu, but add smart convenient methods / shortcuts and a more rubyish feeling
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
260 * No game logic allowed in GameObject, since that's not likely to be useful for others.
700c950 @ippa big README update
authored
261
9d2d0c2 @ippa New Chingu tagline. Updated and fixes for docs across the whole lib. …
authored
262 It's based around Image#draw_rot. So basically all the arguments that you pass to draw_rot can be passed to GameObject#new when creating a new object.
263 An example using almost all arguments would be:
700c950 @ippa big README update
authored
264
265 #
266 # You probably recognize the arguments from http://www.libgosu.org/rdoc/classes/Gosu/Image.html#M000023
267 #
268 @player = Player.new(:image => Image["player.png"], :x=>100, :y=>100, :zorder=>100, :angle=>45, :factor_x=>10, :factor_y=>10, :center_x=>0, :center_y=>0)
269
270 #
271 # A shortcut for the above line would be
272 #
3d68151 README updates and fixes to reflect on recent changes
ippa authored
273 @player = Player.new(:image => "player.png", :x=>100, :y=>100, :zorder=>100, :angle=>45, :factor=>10, :center=>0)
700c950 @ippa big README update
authored
274
275 #
276 # I've tried doing sensible defaults:
5c7b343 @ippa README.rdoc update and spellfixes
authored
277 # x/y = [middle of the screen] for super quick display where it should be easy in sight)
700c950 @ippa big README update
authored
278 # angle = 0 (no angle by default)
5c7b343 @ippa README.rdoc update and spellfixes
authored
279 # center_x/center_y = 0.5 (basically the center of the image will be drawn at x/y)
700c950 @ippa big README update
authored
280 # factor_x/factor_y = 1 (no zoom by default)
281 #
282 @player = Player.new
283
284 #
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
285 # By default Chingu::Window calls update & draw on all GameObjects in it's own update/draw.
700c950 @ippa big README update
authored
286 # If this is not what you want, use :draw and :update
287 #
288 @player = Player.new(:draw => false, :update => false)
289
a3f161e @ippa readme update
authored
290 === Input
291 One of the core things I wanted a more natural way of inputhandling.
292 You can define input -> actions on Chingu::Window, Chingu::GameState and Chingu::GameObject.
293 Like this:
294
295 #
296 # When left arrow is pressed, call @player.turn_left ... and so on.
297 #
298 @player.input = { :left => :turn_left, :right => :turn_right, :left => :halt_left, :right => :halt_right }
299
300
301 #
302 # In Gosu the equivalent would be:
303 #
304 def button_down(id)
305 @player.turn_left if id == Button::KbLeft
306 @player.turn_right if id == Button::KbRight
307 end
308
309 def button_up(id)
310 @player.halt_left if id == Button::KbLeft
311 @player.halt_right if id == Button::KbRight
312 end
313
314
315 Another more complex example:
316
317 #
318 # So what happens here?
319 #
320 # Pressing P would create an game state out of class Pause, cache it and activate it.
321 # Pressing ESC would call Play#close
322 # Holding down LEFT would call Play#move_left on every game iteration
323 # Holding down RIGHT would call Play#move_right on every game iteration
cfa1e45 @jduff little fix to one ofthe examples in the docs, a bunch of spelling
jduff authored
324 # Releasing SPACE would call Play#fire
a3f161e @ippa readme update
authored
325 #
326
327 class Play < Chingu::GameState
328 def initialize
b66d53f @ippa README updates and fixes
authored
329 self.input = { :p => Pause,
330 :escape => :close,
331 :holding_left => :move_left,
332 :holding_right => :move_right,
333 :released_space => :fire }
a3f161e @ippa readme update
authored
334 end
335 end
336 class Pause < Chingu::GameState
337 # pause logic here
338 end
339
340 In Gosu the above code would include code in button_up(), button_down() and a check for button_down?() in update().
341
342 Every symbol can be prefixed by either "released_" or "holding_" while no prefix at all defaults to pressed once.
343
cfa1e45 @jduff little fix to one ofthe examples in the docs, a bunch of spelling
jduff authored
344 So, why not :up_space or :release_space instead of :released_space?
b66d53f @ippa README updates and fixes
authored
345 +:up_space+ doesn't sound like english, :release_space sounds more like a command then an event.
a3f161e @ippa readme update
authored
346
b66d53f @ippa README updates and fixes
authored
347
8481eed @ippa github didn't turn + and * into bold and typewriterfont as I wanted
authored
348 Or +:hold_left+ or :down_left instead of :holding_left?
349 :holding_left sounds like something that's happening over a period of time, not a single trigger, which corresponds well to how it works.
a3f161e @ippa readme update
authored
350
cfa1e45 @jduff little fix to one ofthe examples in the docs, a bunch of spelling
jduff authored
351 And with the default :space => :something you would imagine that :something is called once. You press :space once, :something is executed once.
a3f161e @ippa readme update
authored
352
353
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
354 === GameState / GameStateManager
5c7b343 @ippa README.rdoc update and spellfixes
authored
355 Chingu incorporates a basic push/pop game state system (as discussed here: http://www.gamedev.net/community/forums/topic.asp?topic_id=477320).
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
356
5c7b343 @ippa README.rdoc update and spellfixes
authored
357 Game states is a way of organizing your intros, menus, levels.
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
358
5c7b343 @ippa README.rdoc update and spellfixes
authored
359 Game states aren't complicated. In Chingu a GameState is a class that behaves mostly like your default Gosu::Window (or in our case Chingu::Window) game loop.
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
360
361
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
362 # A simple GameState-example
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
363 class Intro < Chingu::GameState
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
364
668deec @ippa Make README clearer regarding how game states work + doc bugfixes in …
authored
365 def initialize(options)
366 # called as usual when class is created, load resources and simular here
367 end
368
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
369 def update
5c7b343 @ippa README.rdoc update and spellfixes
authored
370 # game logic here
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
371 end
372
373 def draw
374 # screen manipulation here
375 end
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
376
668deec @ippa Make README clearer regarding how game states work + doc bugfixes in …
authored
377 # Called Each time when we enter the game state, use this to reset the gamestate to a "virgin state"
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
378 def setup
379 @player.angle = 0 # point player upwards
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
380 end
381
b66d53f @ippa README updates and fixes
authored
382 # Called when we leave the game state
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
383 def finalize
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
384 push_game_state(Menu) # switch to game state "Menu"
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
385 end
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
386
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
387 end
388
cfa1e45 @jduff little fix to one ofthe examples in the docs, a bunch of spelling
jduff authored
389 Looks familiar yet?
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
390 You can activate the above game state in 2 ways
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
391
392 class Game < Chingu::Window
393 def initialize
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
394 #
395 # 1) Create a new Intro-object and activate it (pushing to the top).
396 # This version makes more sense if you want to pass parameters to the gamestate, for example:
397 # push_game_state(Level.new(:level_nr => 10))
398 #
399 push_game_state(Intro.new)
400
401 #
402 # 2) This leaves the actual object-creation to the game state manager.
31b2b88 @ippa remove some game state cache magic, internal rename in game state man…
authored
403 # Intro#initialize() is called, then Intro#setup()
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
404 #
405 push_game_state(Intro)
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
406 end
407 end
54ec455 @ippa More about game states in README, new commented example
authored
408
409 Another example:
410
411 class Game < Chingu::Window
412 def initialize
413 #
830a9a5 @spilth Fixed some of the GameStateManager method descriptions
spilth authored
414 # We start by pushing Menu to the game state stack, making it active as it's the only state on stack.
415 #
416 # :setup => :false will skip setup() from being called (standard when switching to a new state)
54ec455 @ippa More about game states in README, new commented example
authored
417 #
418 push_game_state(Menu, :setup => false)
419
420 #
cfa1e45 @jduff little fix to one ofthe examples in the docs, a bunch of spelling
jduff authored
421 # We push another game state to the stack, Play. We now have 2 states, which active being first / active.
54ec455 @ippa More about game states in README, new commented example
authored
422 #
830a9a5 @spilth Fixed some of the GameStateManager method descriptions
spilth authored
423 # :finalize => false will skip finalize() from being called on game state
424 # that's being pushed down the stack, in this case Menu.finalize().
54ec455 @ippa More about game states in README, new commented example
authored
425 #
426 push_game_state(Play, :finalize => false)
427
428 #
830a9a5 @spilth Fixed some of the GameStateManager method descriptions
spilth authored
429 # Next, we remove Play state from the stack, going back to the Menu-state. But also:
54ec455 @ippa More about game states in README, new commented example
authored
430 # .. skipping the standard call to Menu#setup (the new game state)
431 # .. skipping the standard call to Play#finalize (the current game state)
432 #
433 # :setup => false can for example be useful when pop'ing a Pause game state. (see example4.rb)
434 #
435 pop_game_state(:setup => false, :finalize => :false)
436
437 #
438 # Replace the current game state with a new one.
830a9a5 @spilth Fixed some of the GameStateManager method descriptions
spilth authored
439 #
440 # :setup and :finalize options are available here as well but:
441 # .. setup and finalize are always skipped for Menu (the state under Play and Credits)
442 # .. the finalize option only affects the popped game state
443 # .. the setup option only affects the game state you're switching to
54ec455 @ippa More about game states in README, new commented example
authored
444 #
445 switch_game_state(Credits)
446 end
447 end
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
448
5c7b343 @ippa README.rdoc update and spellfixes
authored
449 A GameState in Chingu is just a class with the following instance methods:
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
450
668deec @ippa Make README clearer regarding how game states work + doc bugfixes in …
authored
451 * initialize() - as you might expect, called when GameState is created.
452 * setup() - called each time the game state becomes active.
453 * button_down(id) - called when a button is down.
454 * button_up(id) - called when a button is released.
54ec455 @ippa More about game states in README, new commented example
authored
455 * update() - just as in your normal game loop, put your game logic here.
456 * draw() - just as in your normal game loop, put your screen manipulation here.
457 * finalize() - called when a game state de-activated (for example by pushing a new one on top with push_game_state)
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
458
5c7b343 @ippa README.rdoc update and spellfixes
authored
459 Chingu::Window automatically creates a @game_state_manager and makes it accessible in our game loop.
460 By default the game loop calls update() / draw() on the the current game state.
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
461
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
462 Chingu also has a couple of helpers-methods for handling the game states:
5c7b343 @ippa README.rdoc update and spellfixes
authored
463 In a main loop or in a game state:
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
464 * push_game_state(state) - adds a new gamestate on top of the stack, which then becomes the active one
465 * pop_game_state - removes active gamestate and activates the previous one
54ec455 @ippa More about game states in README, new commented example
authored
466 * switch_game_state(state) - replaces current game state with a new one
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
467 * current_game_state - returns the current game state
468 * previous_game_state - returns the previous game state (useful for pausing and dialog boxes, see example4.rb)
469 * pop_until_game_state(state) - pop game states until given state is found
470 * clear_game_states - removes all game states from stack
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
471
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
472 To switch to a certain gamestate with a keypress use Chingus input handler:
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
473 class Intro < Chingu::GameState
474 def setup
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
475 self.input = { :space => lambda{push_gamestate(Menu.new)} }
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
476 end
477 end
478
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
479 Or Chingus shortcut:
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
480
481 class Intro < Chingu::GameState
482 def setup
54ec455 @ippa More about game states in README, new commented example
authored
483 self.input = { :space => Menu }
7619f4f @ippa Major internal rewrite. New GameState system with 1 example. Docs.
authored
484 end
485 end
54ec455 @ippa More about game states in README, new commented example
authored
486
668deec @ippa Make README clearer regarding how game states work + doc bugfixes in …
authored
487 Chingus inputhandler will detect that Menu is a GameState-class, create a new instance and activate it with push_game_state().
700c950 @ippa big README update
authored
488
b54b7e5 added gotcha in readme
ippa authored
489 GOTCHA: Currently you can't switch to a new game state from Within GameState#initialize() or GameState#setup()
490
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
491 === Premade game states
492 Chingu comes with some pre-made game states.
493 A simple but usefull one is GameStates::Pause. Once pushed it will draw the previous game state but not update it --
051f012 Write about GameStates::EnterName in README. Everyone planning to use…
ippa authored
494 effectively pausing it. Some others are:
495
496 == GameStates::EnterName
497 A gamestate where a gamer can select letters from a A-Z list, contructing his alias. When he's done he selects "GO!" and a
498 developer-specified callback will be called with the name/alias as argument.
499
500 push_game_state GameStates::EnterName.new(:callback => method(:add))
501
502 def add(name)
503 puts "User entered name #{name}"
504 end
505
506 Combine GameStates::EnterName with class OnlineHighScoreList, a free acount @ www.gamercv.com and you have a premade stack to
507 provide your 48h gamecompo entry with online high scores that adds an extra dimension to your game. See example16 for a full working example of this.
508
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
509
cc31df6 Document new Editor better
ippa authored
510 == GameStates::Edit
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
511 The biggest and most usable is GameStates::Edit which enables fast 'n easy level-building with game objects.
512 Start example19 and press 'E' to get a full example.
513
514 Edit commands / shortcuts:
01205cc README updates
ippa authored
515 F1: Help screen
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
516 1-5: create object 1..5 shown in toolbar at mousecursor
01205cc README updates
ippa authored
517 CTRL+A: select all objects (not in-code-created ones though)
cc31df6 Document new Editor better
ippa authored
518 CTRL+S: Save
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
519 E: Save and Quit
01205cc README updates
ippa authored
520 Q: Quit (without saving)
cc31df6 Document new Editor better
ippa authored
521 ESC: Deselect all objects
01205cc README updates
ippa authored
522 Right Mouse Button Click: Copy object bellow cursor for fast duplication
cc31df6 Document new Editor better
ippa authored
523 Arrow-keys (with selected objects): Move objects 1 pixel at the time
524 Arrow-keys (with no selected objects): Scroll within a viewport
525
01205cc README updates
ippa authored
526
527 Bellow keys operates on all currently selected game objects
528 -----------------------------------------------------------------------------------
529 DEL: delete selected objects
530 BACKSPACE: reset angle and scale to default values
531 Page Up: Increase zorder
532 Page Down: Decrease zorder
cc31df6 Document new Editor better
ippa authored
533
01205cc README updates
ippa authored
534 R: scale up
535 F: scale down
536 T: tilt left
537 G: tilt right
538 Y: inc zorder
539 H: dec zorder
540 U: less transparency
755e5e1 fix
ippa authored
541 J: more transparency
01205cc README updates
ippa authored
542
cc31df6 Document new Editor better
ippa authored
543 Mouse Wheel (with no selected objects): Scroll viewport up/down
544 Mouse Wheel: Scale up/down
545 SHIFT + Mouse Wheel: Tilt left/right
546 CTRL + Mouse Wheel: Zorder up/down
01205cc README updates
ippa authored
547 ALT + Mouse Wheel: Transparency less/more
cc31df6 Document new Editor better
ippa authored
548
549 Move mouse cursor close to the window border to scroll a viewport if your game state has one.
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
550
551 If you're editing game state BigBossLevel the editor will save to big_boss_level.yml by default.
552 All the game objects in that file are then easily loaded with the load_game_objects command.
553
554 Both Edit.new and load_game_objects take parameters as
555 :file => "enemies.yml" # Save edited game objects to file enemies.yml
556 :debug => true # Will print various debugmsgs to console, usefull if something behaves oddly
557 :except => Player # Don't edit or load objects based on class Player
558
3d68151 README updates and fixes to reflect on recent changes
ippa authored
559 === WorkFlow
560 (This text is under development)
561
562 == The setup-method
563 If a setup() is available in a instance of Chingu::GameObject, Chingu::Window and Chingu::GameState it will automatically be called.
0825f85 goodbuy automatic_assets-trait, hello animation-trait (automatic load…
ippa authored
564 This is the perfect spot to include various setup/init-tasks like setting colors or loading animations (if you're not using the animation-trait).
3d68151 README updates and fixes to reflect on recent changes
ippa authored
565 You could also override initialize() for this purpose but it's been proven prone to errors again and again.
566 Compare the 2 snippets below:
567
568 # Easy to mess up, forgetting options or super
569 def initialize(options = {})
570 super
571 @color = Color::WHITE
572 end
573
574 # Less code, easier to get right and works in GameObject, Window and GameState
575 # Feel free to call setup() anytime, there's no magic about ut except it's autocalled once on object creation time.
576 def setup
577 @color = Color::WHITE
578 end
579
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
580 === Traits
3d68151 README updates and fixes to reflect on recent changes
ippa authored
581 Traits (sometimes called behaviors in other frameworks) is a way of adding logic to any class inheriting from BasicGameObject / GameObject.
0a8e0f5 @ippa README additions
authored
582 Chingus trait-implementation is just ordinary ruby modules with 3 special methods:
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
583 - setup_trait
584 - update_trait
585 - draw_trait
586 Each of those 3 methods must call "super" to continue the trait-chain.
587
0a8e0f5 @ippa README additions
authored
588 Inside a certian trait-module you can also have a module called ClassMethods, methods inside that module will be added,
589 yes you guessed it, as class methods. If initialize_trait is defined inside ClassMethods it will be called class-evaluation time
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
590 (basicly on the trait :some_trait line).
0a8e0f5 @ippa README additions
authored
591
592 A simple trait could be:
593
d169eb1 various readme updates
ippa authored
594 module Chingu
595 module Trait
596 module Inspect
3d68151 README updates and fixes to reflect on recent changes
ippa authored
597
d169eb1 various readme updates
ippa authored
598 #
599 # methods namespaced to ClassMethods get's extended as ... class methods!
600 #
601 module ClassMethods
602 def initialize_trait(options)
0a8e0f5 @ippa README additions
authored
603 # possible initialize stuff here
d169eb1 various readme updates
ippa authored
604 end
605
606 def inspect
607 "There's {self.size} active instances of class {self.to_s}"
608 end
0a8e0f5 @ippa README additions
authored
609 end
610
d169eb1 various readme updates
ippa authored
611 #
3b938a8 readme updates and fixes
ippa authored
612 # Since it's namespaced outside ClassMethods it becomes a normal instance-method
d169eb1 various readme updates
ippa authored
613 #
0a8e0f5 @ippa README additions
authored
614 def inspect
d169eb1 various readme updates
ippa authored
615 "Hello I'm an #{self.class.to_s}"
0a8e0f5 @ippa README additions
authored
616 end
3b938a8 readme updates and fixes
ippa authored
617
618 #
619 # setup_trait is called when a object is created from a class that included the trait
620 # you most likely want to put all the traits settings and option parsing here
621 #
622 def setup_trait(options)
623 @long_inspect = true
624 end
3d68151 README updates and fixes to reflect on recent changes
ippa authored
625
626 end
0a8e0f5 @ippa README additions
authored
627 end
628 end
629
d169eb1 various readme updates
ippa authored
630 class Enemy < GameObject
631 trait :inspect # includes Chingu::Trait::Inspect and extends Chingu::Trait::Inspect::ClassMethods
632 end
633 10.times { Enemy.create }
634 Enemy.inspect # => "There's 10 active instances of class Enemy"
635 Enemy.all.first.inspect # => "Hello I'm a Enemy"
0a8e0f5 @ippa README additions
authored
636
637
d6e340b mention GameObject#setup as an GameObject#initialize alternative in r…
ippa authored
638 Example of using traits :velocity and :timer.
639 We also use GameObject#setup which will automtically be called ad the end of GameObject#initialize.
640 It's often a little bit cleaner to use setup() then to override initialize().
62df2a7 @ippa README updates, a simple trait-example. Image#retrofy now returns sel…
authored
641
642 class Ogre < Chingu::GameObject
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
643 traits :velocity, :timer
d6e340b mention GameObject#setup as an GameObject#initialize alternative in r…
ippa authored
644
645 def setup
62df2a7 @ippa README updates, a simple trait-example. Image#retrofy now returns sel…
authored
646 @red = Gosu::Color.new(0xFFFF0000)
647 @white = Gosu::Color.new(0xFFFFFFFF)
648
649 #
650 # some basic physics provided by the velocity-trait
651 # These 2 parameters will affect @x and @y every game-iteration
652 # So if your ogre is standing on the ground, make sure you cancel out the effect of @acceleration_y
653 #
0a8e0f5 @ippa README additions
authored
654 self.velocity_x = 1 # move constantly to the right
655 self.acceleration_y = 0.4 # gravity is basicly a downwards acceleration
62df2a7 @ippa README updates, a simple trait-example. Image#retrofy now returns sel…
authored
656 end
657
658 def hit_by(object)
659 #
660 # during() and then() is provided by the timer-trait
661 # flash red for 300 millisec when hit, then go back to normal
662 #
0a8e0f5 @ippa README additions
authored
663 during(100) { self.color = @red; self.mode = :additive }.then { self.color = @white; self.mode = :default }
62df2a7 @ippa README updates, a simple trait-example. Image#retrofy now returns sel…
authored
664 end
665 end
666
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
667 The flow for a game object then becomes:
668
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
669 -- creating a GameObject class X ( with a "trait :bounding_box, :scale => 0.80" )
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
670 1) trait gets merged into X, instance and class methods are added
0a8e0f5 @ippa README additions
authored
671 2) GameObject.initialize_trait(:scale => 0.80) (initialize_trait is a class-method!)
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
672 -- creating an instance of X
a2e8f20 @ippa README fix
authored
673 1) GameObject#initialize(options)
674 2) GameObject#setup_trait(options)
3f4ed59 tweaks
ippa authored
675 3) GameObject#setup(options)
a2e8f20 @ippa README fix
authored
676 -- each game iteration
677 3) GameObject#draw_trait
678 4) GameObject#draw
679 5) GameObject#update_trait
680 6) GameObject#update
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
681
682 There's a couple of traits included as default in Chingu:
683
3b938a8 readme updates and fixes
ippa authored
684 ==== Trait "sprite"
685 This trait fuels GameObject. A GameObject is a BasicGameObject + the sprite-trait.
686 Adds accessors :x, :y, :angle, :factor_x, :factor_y, :center_x, :center_y, :zorder, :mode, :visible, :color.
687 See documentation for GameObject for how it works.
688
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
689 ==== Trait "timer"
f9fd433 @ippa Various README updates, biggest beeing a description of the execution…
authored
690 Adds timer functionality to your game object
3d68151 README updates and fixes to reflect on recent changes
ippa authored
691 during(300) { self.color = Color.new(0xFFFFFFFF) } # forces @color to white every update for 300 ms
692 after(400) { self.destroy } # destroy object after 400 ms
693 between(1000,2000) { self.angle += 10 } # starting after 1 second, modify angleevery update during 1 second
694 every(2000) { Sound["bleep.wav"].play } # play bleep.wav every 2 seconds
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
695
696 ==== Trait "velocity"
f9fd433 @ippa Various README updates, biggest beeing a description of the execution…
authored
697 Adds accessors velocity_x, velocity_y, acceleration_x, acceleration_y, max_velocity to game object.
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
698 They modify x, y as you would expect. *speed / angle will come*
699
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
700 ==== Trait "bounding_box"
d169eb1 various readme updates
ippa authored
701 Adds accessor 'bounding_box', which returns an instance of class Rect based on current image size,x,y,factor_x,factor_y,center_x,center_y
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
702 You can also scale the calculated rect with trait-options:
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
703
704 # This would return a rect slightly smaller then the image.
705 # Make player think he's better @ dodging bullets then he really is ;)
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
706 trait :bounding_box, :scale => 0.80
ab2e34e @ippa readme fixes and formating
authored
707
708 # Make the bounding box bigger then the image
709 # :debug => true shows the actual box in red on the screen
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
710 trait :bounding_box, :scale => 1.5, :debug => true
d169eb1 various readme updates
ippa authored
711
712 Inside your object you will also get a cache_bounding_box(). After that the bounding_box will be quicker but it will not longer adapt to size-changes.
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
713
0a8e0f5 @ippa README additions
authored
714 ==== Trait "bounding_circle"
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
715 Adds accessor 'radius', which returns a Fixnum based on current image size,factor_x and factor_y
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
716 You can also scale the calculated radius with trait-options:
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
717
718 # This would return a radius slightly bigger then what initialize was calculated
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
719 trait :bounding_circle, :scale => 1.10
ab2e34e @ippa readme fixes and formating
authored
720
721 # :debug => true shows the actual circle in red on the screen
7009e62 document GameStates::Edit in readme + various other fixes
ippa authored
722 trait :bounding_circle, :debug => true
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
723
d169eb1 various readme updates
ippa authored
724 Inside your object you will also get a cache_bounding_circle(). After that radius() will be quicker but it will not longer adapt to size-changes.
725
0825f85 goodbuy automatic_assets-trait, hello animation-trait (automatic load…
ippa authored
726 ==== Trait "animation"
727 Automatically load animations depending on the class-name.
728 Useful when having a lot of simple classes thats mainpurpose is displaying an animation.
3dae48f README documentation for trait automatic_assets + fixed tabspacing in…
ippa authored
729 Assuming the below code is included in a class FireBall.
730
0825f85 goodbuy automatic_assets-trait, hello animation-trait (automatic load…
ippa authored
731 #
732 # If a fire_ball_10x10.png/bmp exists, it will be loaded as a tileanimation.
3dae48f README documentation for trait automatic_assets + fixed tabspacing in…
ippa authored
733 # 10x10 would indicate the width and height of each tile so Chingu knows hows to cut it up into single frames.
0825f85 goodbuy automatic_assets-trait, hello animation-trait (automatic load…
ippa authored
734 # The animation will then be available in animations[:default] as an Animation-instance.
3d68151 README updates and fixes to reflect on recent changes
ippa authored
735 #
0825f85 goodbuy automatic_assets-trait, hello animation-trait (automatic load…
ippa authored
736 # If more then 1 animation exist, they'll will be loaded at the same time, for example:
737 # fire_ball_10x10_fly.png # Will be available in animations[:fly] as an Animation-instance
738 # fire_ball_10x10_explode.png # Will be available in animations[:explode] as an Animation-instance
3d68151 README updates and fixes to reflect on recent changes
ippa authored
739 #
740 # The below example will set the 200ms delay between each frame on all animations loaded.
741 #
d169eb1 various readme updates
ippa authored
742 trait :animation, :delay => 200
3dae48f README documentation for trait automatic_assets + fixed tabspacing in…
ippa authored
743
f9fd433 @ippa Various README updates, biggest beeing a description of the execution…
authored
744 ==== Trait "effect"
745 Adds accessors rotation_rate, fade_rate and scale_rate to game object.
746 They modify angle, alpha and factor_x/factor_y each update. Since this is pretty easy to do yourself this trait might be up for deprecation.
2348fe1 document game state trait viewport
ippa authored
747
d169eb1 various readme updates
ippa authored
748 ==== Trait "viewport"
2348fe1 document game state trait viewport
ippa authored
749 A game state trait. Adds accessor *viewport*. Set viewport.x and viewport.y to.
750 Basically what viewport.x = 10 will do is draw all game objects 10 pixels to the left of their ordinary position.
751 Since the viewport has moved 10 pixels to the right, the game objects will be seen "moving" 10 pixels to the left.
d169eb1 various readme updates
ippa authored
752 This is great for scrolling games. You also have:
753
754 viewport.game_area = [0,0,1000,400] # Set scrolling limits, the effective game world if you so will
755 viewport.center_around(object) # Center viweport around an object which responds to x() and y()
756
757 viewport.lag = 0.95 # Set a lag-factor to use in combination with x_target / y_target
758 viewport.x_target = 100 # This will move viewport towards X-coordinate 100, the speed is determined by the lag-parameter.
2348fe1 document game state trait viewport
ippa authored
759
a6f2072 add project using chingu + mention parallax/viewport problem in readme
ippa authored
760 NOTE: Doing Parallax.create when using a trait viewport will give bad results.
761 If you need parallax together with viewport do Parallax.new and then manually doing parallax.update/draw.
762
d169eb1 various readme updates
ippa authored
763 ==== Trait "collision_detection"
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
764 Adds class and instance methods for basic collision detection.
765
766 # Class method example
767 # This will collide all Enemy-instances with all Bullet-instances using the attribute #radius from each object.
727c8f4 @ippa more collision detection work, radius_collision? is now bounding_circ…
authored
768 Enemy.each_bounding_circle_collision(Bullet) do |enemy, bullet|
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
769 end
770
771 # You can also use the instance methods. This will use the Rect bounding_box from @player and each EnemyRocket-object.
772 @player.each_bounding_box_collision(EnemyRocket) do |player, enemyrocket|
773 player.die!
774 end
0a8e0f5 @ippa README additions
authored
775
776 #
777 # each_collision automatically tries to access #radius and #bounding_box to see what a certain game object provides
778 # It knows how to collide radius/radius, bounding_box/bounding_box and radius/bounding_box !
779 # Since You're not explicity telling what collision type to use it might be slighty slower.
780 #
781 [Player, PlayerBullet].each_collision(Enemy, EnemyBullet) do |friend, foe|
d169eb1 various readme updates
ippa authored
782 # do something
783 end
0a8e0f5 @ippa README additions
authored
784
d169eb1 various readme updates
ippa authored
785 #
786 # You can also give each_collision() an array of objects.
787 #
788 Ball.each_collsion(@array_of_ground_items) do |ball, ground|
789 # do something
0a8e0f5 @ippa README additions
authored
790 end
d169eb1 various readme updates
ippa authored
791
a60e3a2 updated README explaining asynchronous trait
Eris authored
792 ==== Trait "asynchronous"
793 Allows your code to specify a GameObject's behavior asynchronously, including
7e99ee3 refactor: all confusing operation/instruction terminology replaced wi…
Eris authored
794 tweening, movement and even method calls. Tasks are added to a queue to be
795 processed in order; the task at the front of the queue is updated each tick
796 and removed when it has finished.
a60e3a2 updated README explaining asynchronous trait
Eris authored
797
798 # Simple one-trick example
799 # This will cause an object to move from its current location to 64,64.
2a87e48 changed single-instruction async syntax
Eris authored
800 @guy.async.tween :x => 64, :y => 64
a60e3a2 updated README explaining asynchronous trait
Eris authored
801
802 # Block syntax example
803 # This will cause a line of text to fade out and vanish.
804 Chingu::Text.trait :asynchronous
805 message = Chingu::Text.new 'Goodbye, World!'
806 message.async do |q|
807 q.wait 500
808 q.tween 2000, :alpha => 0, :scale => 2
809 q.call :destroy
810 end
811
7e99ee3 refactor: all confusing operation/instruction terminology replaced wi…
Eris authored
812 Currently available tasks are wait(timeout, &condition), tween(timeout,
7240ef0 README reflects addition of exec op
Eris authored
813 properties), call(method, *arguments) and exec { ... }.
a60e3a2 updated README explaining asynchronous trait
Eris authored
814
815 For a more complete example of how to use this trait, see
816 examples/example_async.rb.
817
818
819
a2e8f20 @ippa README fix
authored
820 ==== (IN DEVELOPMENT) Trait "retrofy"
4055869 @ippa alot of small fixes and cleanups. Paralaxx-class can now repeat textu…
authored
821 Providing easier handling of the "retrofy" effect (non-blurry zoom)
822 Aims to help out when using zoom-factor to create a retrofeeling with big pixels.
823 Provides screen_x and screen_y which takes the zoom into account
824 Also provides new code for draw() which uses screen_x / screen_y instead of x / y
825
826
62df2a7 @ippa README updates, a simple trait-example. Image#retrofy now returns sel…
authored
827
700c950 @ippa big README update
authored
828 === Assets / Paths
179ae00 @ippa readme updates, examples etc
authored
829
cfa1e45 @jduff little fix to one ofthe examples in the docs, a bunch of spelling
jduff authored
830 You might wonder why this is necessary in the straight Gosu example:
179ae00 @ippa readme updates, examples etc
authored
831 ROOT_PATH = File.dirname(File.expand_path(__FILE__))
832 @image = Image.new(File.join(ROOT_PATH, "media", "player.png"))
833
dec2095 @ippa readme
authored
834 It enables you to start your game from any directory and it will still find your assets (pictures, samples, fonts etc..) correctly.
5c7b343 @ippa README.rdoc update and spellfixes
authored
835 For a local development version this might not be important, you're likely to start the game from the games root-dir.
cfa1e45 @jduff little fix to one ofthe examples in the docs, a bunch of spelling
jduff authored
836 But as soon as you try to deploy (for example to windows with OCRA - http://github.com/larsch/ocra/tree/master) you'll run into trouble of you don't do it like that.
179ae00 @ippa readme updates, examples etc
authored
837
838 Chingu solves this problem behind the scenes for the most common assets. The 2 lines above can be replaced with:
b66d53f @ippa README updates and fixes
authored
839 Image["player.png"]
840
841 You also have:
b34e818 @ippa small README-fix by apillet. Bugfix in gfx draw_circle.
authored
842 Sound["shot.wav"]
b66d53f @ippa README updates and fixes
authored
843 Song["intromusic.ogg"]
0fb6fca document Font[] in readme
ippa authored
844 Font["arial"]
845 Font["verdana", 16] # 16 is the size of the font
846
9b850a6 @ippa better docs about default asset directories
authored
847 The default settings are like this:
ab2e34e @ippa readme fixes and formating
authored
848 Image["image.png"] -- searches directories ".", "images", "gfx" and "media"
849 Sample["sample.wav"] -- searches directories ".", "sounds", "sfx" and "media"
850 Song["song.ogg"] -- searches directories ".", "songs", "sounds", "sfx" and "media"
0fb6fca document Font[] in readme
ippa authored
851 Font["verdana"] -- searches directories ".", "fonts", "media"
9b850a6 @ippa better docs about default asset directories
authored
852
b66d53f @ippa README updates and fixes
authored
853 Add your own searchpaths like this:
9b850a6 @ippa better docs about default asset directories
authored
854 Gosu::Image.autoload_dirs << File.join(ROOT, "gfx")
855 Gosu::Sound.autoload_dirs << File.join(ROOT, "samples")
b66d53f @ippa README updates and fixes
authored
856
8481eed @ippa github didn't turn + and * into bold and typewriterfont as I wanted
authored
857 This will add \path\to\your\game\gfx and \path\to\your\game\samples to Image and Sound.
b66d53f @ippa README updates and fixes
authored
858
859 Thanks to Jacious of rubygame-fame (http://rubygame.org/) for his named resource code powering this.
179ae00 @ippa readme updates, examples etc
authored
860
5c7b343 @ippa README.rdoc update and spellfixes
authored
861 === Text
862 Text is a class to give the use of Gosu::Font more rubyish feel and fit it better into Chingu.
863
864 # Pure Gosu
865 @font = Gosu::Font.new($window, "verdana", 30)
866 @font.draw("A Text", 200, 50, 55, 2.0)
867
868 # Chingu
0a8e0f5 @ippa README additions
authored
869 @text = Chingu::Text.create("A Text", :x => 200, :y => 50, :zorder => 55, :factor_x => 2.0)
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
870 @text.draw
5c7b343 @ippa README.rdoc update and spellfixes
authored
871
36f1d24 readme fixes
unknown authored
872 @text.draw is usually not needed as Text is a GameObject and therefore automatically updated/drawn (it #create is used instead of #new)
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
873 It's not only that the second example is readable by ppl now even familiar with Gosu, @text comes with a number of changeable properties, x,y,zorder,angle,factor_x,color,mode etc.
874 Set a new x or angle or color and it will instantly update on screen.
5c7b343 @ippa README.rdoc update and spellfixes
authored
875
7ac9722 @ippa first commit
authored
876
26235fd add deprecation-section in README
ippa authored
877 == DEPRECATIONS
878 Chingu (as all libraries) will sometimes break an old API. Naturally we try to not do this, but sometimes it's nessesary
879 to take the library forward. If your old game stops working with a new chingu it could depend on some of the following:
880
881 Listing game objects:
882 class Enemy < GameObject; end;
883 class Troll < Enemy; end;
884 class Witch < Enemy; end;
885
886 Chingu 0.7
887 Enemy.all # Will list objects created with Enemy.create, Troll.create, Witch.create
888
889 Chingu ~0.8+
890 Enemy.all # list only list objects created with Enemy.create
891
892 We gained a lot of speed breaking that API.
893
894
b66d53f @ippa README updates and fixes
authored
895 == MISC / FAQ
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
896 === How do I access my main-window easily?
8481eed @ippa github didn't turn + and * into bold and typewriterfont as I wanted
authored
897 Chingu keeps a global variable, $window, which contains the Chingu::Window instance.
b66d53f @ippa README updates and fixes
authored
898 Since Chingu::Window is just Gosu::Window + some cheese you can do your $window.button_down?, $window.draw_line() etc from anywhere.
899 See http://www.libgosu.org/rdoc/classes/Gosu/Window.html for a full set of methods.
900
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
901 === How did you decide on naming of methods / classes?
902 There's 1 zillion ways of naming stuff. As a general guideline I've tried to follow Gosus naming.
2c70414 @ippa readme fixes
authored
903 If Gosu didn't have a good name for a certain thing/method I've checked Ruby itself and then Rails since alot of Ruby-devs are familiar with Rails.
904 GameObject.all is naming straight from rails for example. Most stuff in GameObject follow the naming from Gosus Image#draw_rot.
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
905
9d2d0c2 @ippa New Chingu tagline. Updated and fixes for docs across the whole lib. …
authored
906 As far as possible, use correct rubyfied english game_objects, not gameobjects. class HighScore, not Highscore.
907
3d68151 README updates and fixes to reflect on recent changes
ippa authored
908
909 == WHY?
910 * Plain Gosu is very minimalistic, perfect to build some higher level logic on!
911 * Deployment and asset handling should be simple
912 * Managing game states/scenes (intros, menus, levels etc) should be simple
d85fa8e readme updates/fixes
ippa authored
913 * There are a lot patterns in game development
3d68151 README updates and fixes to reflect on recent changes
ippa authored
914
915 == OPINIONS
916 * Less code is usually better
917 * Hash arguments FTW. And it becomes even better in 1.9.
918 * Don't separate too much from Gosus core-naming
919
920 == CREDITS:
3b938a8 readme updates and fixes
ippa authored
921 * Spooner (input-work, tests and various other patches)
922 * Jacob Huzak (sprite-trait, tests etc)
3d68151 README updates and fixes to reflect on recent changes
ippa authored
923 * Jacius of Rubygame (For doing cool stuff that's well documented as re-usable). So far rect.rb and named_resource.rb is straight outta Rubygame.
924 * Banister (of texplay fame) for general feedeback and help with ruby-internals and building the trait-system
925 * Jduff for input / commits
3dab73a spelling fix
ippa authored
926 * Jlnr,Philomory,Shawn24,JamesKilton for constructive feedback/discussions
3d68151 README updates and fixes to reflect on recent changes
ippa authored
927 * Ariel Pillet for codesuggestions and cleanups
928 * Deps for making the first real full game with Chingu (and making it better in the process)
929 * Thanks to http://github.com/tarcieri for require_all code, good stuff
d85fa8e readme updates/fixes
ippa authored
930 .. Did I forget anyone here? Msg me on github.
3d68151 README updates and fixes to reflect on recent changes
ippa authored
931
932 == REQUIREMENTS:
d85fa8e readme updates/fixes
ippa authored
933 * Gosu, preferable the latest version
3d68151 README updates and fixes to reflect on recent changes
ippa authored
934 * Ruby 1.9.1+ or 1.8.7+
935 * gem 'texplay' for some bonus Image-pixel operations, not needed otherwise
936
937 == TODO - this list is Discontinued and no longer updated!
cf2b3c2 @ippa components -> traits. everything now works with 1.8.7 and 1.9.1. vari…
authored
938 * add :padding and :align => :topleft etc to class Text
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
939 * (skip) rename Chingu::Window so 'include Chingu' and 'include Gosu' wont make Window collide
cf2b3c2 @ippa components -> traits. everything now works with 1.8.7 and 1.9.1. vari…
authored
940 * (done) BasicObject vs GameObject vs ScreenObject => Became BasicGameObject and GameObject
941 * (50%) some kind of componentsystem for GameObject (which should be cleaned up)
942 * (done) scale <--> growth parameter. See trait "effect"
943 * (done) Enemy.all ... instead of game_objects_of_type(Enemy) ? could this be cool / understandable?
af5b2aa @ippa readme updates
authored
944 * (done) Don't call .update(time) with timeparameter, make time available thru other means when needed.
945 * (10% done) debug screen / game state.. check out shawn24's elite irb sollution :)
2ae593b @ippa Easier gemspec build in Rakefile. Chingu gem 0.2.0 released.
authored
946 * (done) Complete the input-definitions with all possible inputs (keyboard, gamepad, mouse)!
3e1d67d @ippa readme updates + release github gem 0.3.0
authored
947 * (done) Complete input-stuff with released-states etc
c175256 @ippa cleanups
authored
948 * (done) More gfx effects, for example: fade in/out to a specific color (black makes sense between levels).
bb0bf06 @ippa game state related fixes. more consistent naming, new methods, better…
authored
949 * (posted request on forums) Summon good proven community gosu snippets into Chingu
5c7b343 @ippa README.rdoc update and spellfixes
authored
950 * (done) Generate docs @ ippa.github.com- http://rdoc.info/projects/ippa/chingu !
951 * (done) A good scene-manager to manage welcome screens, levels and game flow- GameStateManager / GameState !
54ec455 @ippa More about game states in README, new commented example
authored
952 * (20% done) make a playable simple game in examples\ that really depends on game states
5c7b343 @ippa README.rdoc update and spellfixes
authored
953 * (done) Make a gem- first gem made on github
54ec455 @ippa More about game states in README, new commented example
authored
954 * (done) Automate gemgenning rake-task even more
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
955 * (done) More examples when effects are more complete
4ff81f3 @ippa Actor -> GameObject for our minimal abstract gameclass. save Actor-na…
authored
956 * class ChipmunkObject
73e1c95 @ippa GameObject.new now contains zero magic. GameObject.create works as ne…
authored
957 * (done) class Actor/MovingActor with maybe a bit more logic then the basic GameObject.
af5b2aa @ippa readme updates
authored
958 * (60% done) Spell check all docs, sloppy spelling turns ppl off. tnx jduff ;).
dec2095 @ippa readme
authored
959 * Tests
3e1d67d @ippa readme updates + release github gem 0.3.0
authored
960 * (done) Streamline fps / tick code
5c7b343 @ippa README.rdoc update and spellfixes
authored
961 * (done) Encapsulate Font.new / draw_rot with a "class Text < GameObject"
3e1d67d @ippa readme updates + release github gem 0.3.0
authored
962 * (10% done) Make it possible for ppl to use the parts of Chingu they like
c175256 @ippa cleanups
authored
963 * (done) At least make GameStateManager really easy to use with pure Gosu / Document it!
54ec455 @ippa More about game states in README, new commented example
authored
964 * (50% done) Get better at styling rdocs
b45e324 remove odd utf8 chars from README
ippa authored
965 * (done) all "gamestate" -> "game state"
cf2b3c2 @ippa components -> traits. everything now works with 1.8.7 and 1.9.1. vari…
authored
966 * (skipping) intergrate MovieMaker - solve this with traits instead.
2c37992 @ippa alot of fixes, rotation_center understands :middle, input back in Gam…
authored
967 * A more robust game state <-> game_object system to connect them together.
3e1d67d @ippa readme updates + release github gem 0.3.0
authored
968 * FIX example4: :p => Pause.new would Change the "inside_game_state" to Pause and make @player belong to Pause.
0bbf047 @ippa more docs
authored
969
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
970
9ccbb3f merge old History.txt with readme
ippa authored
971 == Old History, now deprecated:
972
973 === 0.6 / 2009-11-21
974 More traits, better input, fixes
975 This file is deprecated -- see github commit-history instead!
976
977 === 0.5.7 / 2009-10-15
978 See github commithistory.
979
980 === 0.5 / 2009-10-7
981 Big refactor of GameObject. Now has BasicGameObject as base.
982 A first basic "trait"-system where GameObject "has_traits :visual, :velocity" etc.
983 Tons of enhancements and fixes. Speed optimization. More examples.
984
985 === 0.4.5 / 2009-08-27
986 Tons of small fixes across the board.
987 Started on GFX Helpers (fill, fill_rect, fill_gradient so far).
988 A basic particle system (see example7.rb)
989
990 === 0.4.0 / 2009-08-19
991 Alot of game state love. Now also works stand alone with pure gosu.
992
993 === 0.3.0 / 2009-08-14
994 Too much to list. remade inputsystem. gamestates are better. window.rb is cleaner. lots of small bugfixes. Bigger readme.
995
996 === 0.2.0 / 2009-08-10
997 tons of new stuff and fixes. complete keymap. gamestate system. moreexamples/docs. better game_object.
998
999 === 0.0.1 / 2009-08-05
1000 first release
1001
1002
8740bde @ippa big trait-overhaul/refactor, may break your code. replace your has_tr…
authored
1003
1004 "If you program and want any longevity to your work, make a game.
1005 All else recycles, but people rewrite architectures to keep games alive.", _why
1006
3d68151 README updates and fixes to reflect on recent changes
ippa authored
1007
Something went wrong with that request. Please try again.