Initial detailed Readme V1.0

README.md

@@ -1,3 +1,86 @@
-# pong_raylib
+# PONG 2026
 
-Classic pong implemented in Odin and Raylib
+A deliberately over engineered Pong clone in [Odin](https://odin-lang.org) with [raylib](https://www.raylib.com).
+
+Retro line-based graphics with a CRT post-processing shader.
+
+## Screenshots
+
+![Main menu](screenshots/main_menu.png)
+
+![Settings menu](screenshots/settings_menu.png)
+
+![Gameplay](screenshots/gameplay.png)
+
+## Why Over-Engineered?
+
+While the game could have been done in a single file, the goal was to structure the project like a small production game instead:
+
+- **Manager-per-subsystem**: audio, input, event, level, particle, and scene managers, each in its own file
+- **Event system**: decoupled communication between systems (`event_manager.odin`) instead of direct calls
+- **Scene management**: state/scene stack for menus, gameplay, etc. (`scene_manager.odin`)
+- **Entity layer**: shared base entity with ball, player, and opponent specializations
+- **Input abstraction**: keyboard and gamepad behind one interface
+- **Data-driven assets**: audio and shaders loaded from `assets/`, not embedded
+
+The idea behind breaking it into systems is so that it can help build my foundations into more complex games.
+
+## Features
+
+- Single-player vs AI opponent
+- CRT fragment shader (`assets/shaders/crt.fs`)
+- Particle effects, sound effects, music
+- Gamepad support via SDL controller mappings
+
+## Controls
+
+| Action | Keyboard | Gamepad |
+|--------|----------|---------|
+| Move   | W(up) S(down)   | Left Joystick  |
+| Select | Enter   | A button  |
+| Pause  | Spacebar   | Start button  |
+
+## Requirements
+
+Please note, I have not built this on MacOs or Windows, only linux.
+While in theory if you have the odin compiler it should just work as there is no external libs besides those bundled with Odin.
+
+- Odin compiler (version dev-2026-10:e87445a58)
+- raylib (bundled with Odin as `vendor:raylib`)
+- GPU/driver with OpenGL 3.3 support (shader uses `#version 330`)
+
+## Build & Run
+
+    ./build.sh          # see build.sh for flags and options
+    ./out/pong
+
+## Project Layout
+
+    assets/
+      audio/            music, SFX, UI sounds
+      shaders/          crt.fs
+    screenshots/        README images
+    src/
+      main.odin         entry point
+      game.odin         game state and loop
+      *_manager.odin    audio, event, input, level, particle, scene
+      entity*.odin      base entity, ball, player, opponent
+    out/                build output
+    build.sh            build script
+
+## Credits
+Sourced from the web, not mine.
+
+| File | Title | Author | Source | License |
+|------|-------|--------|--------|---------|
+| `...` | TODO | TODO | URL | TODO |
+
+
+### Third-Party
+- `gamecontrollerdb.txt`: [SDL_GameControllerDB](https://github.com/mdqinc/SDL_GameControllerDB) (zlib)
+- [raylib](https://github.com/raysan5/raylib) by Ramon Santamaria (@raysan5), zlib
+- [Odin](https://github.com/odin-lang/Odin), BSD-3-Clause
+
+## License
+MIT, see [LICENSE](LICENSE).
+Any third-party assets retain their original licenses, listed above.

src/entity_ball.odin

@@ -120,6 +120,7 @@ check_ball_paddle_collision :: proc(ball: ^Entity, paddle: Entity) -> bool {
 }
 
 increment_score :: proc(score_side: ^int, max_score: int, player: bool, ball: ^Entity) {
+	emit_event(.Score_Change)
     score_side^ += 1
     if score_side^ == max_score {
         emit_event(Game_Over_Data{player})

src/event_manager.odin

@@ -58,14 +58,6 @@ process_events :: proc(game: ^Game) {
             push_scene(game, make_game_over_overlay(e.winner_is_player))
 
         case Ball_Collision_Data:
-            // normalize the speed between 0.0 -> 1.0
-            // map that value to the camera displacement
-            min_speed: f32 = 200.0
-            max_speed: f32 = 550.0
-            speed_factor := clamp((e.speed - min_speed) / (max_speed - min_speed), 0, 1.0)
-
-            intensity := 0.5 + (speed_factor * 4.5) 
-            game_trigger_shake(game, intensity, duration = 0.15)
             audio_play_sfx(&game.audio, .Ball_Collision)            
 
         case Simple_Event:
@@ -81,6 +73,9 @@ process_events :: proc(game: ^Game) {
             case .Game_Resume:
                 pop_scene(game)
 
+            case .Score_Change:
+            	game_trigger_shake(game, 10, duration = 0.20)
+
             case .Game_Settings:
                 parent: Maybe(Scene_Type) = nil
                 if active := get_active_scene(game); active != nil {

src/game.odin

@@ -6,7 +6,7 @@ import rl "vendor:raylib"
 
 VIEWPORT_W   :: 640
 VIEWPORT_H   :: 360
-WINDOW_TITLE :: "Pong"
+WINDOW_TITLE :: "PONG 2026"
 
 Resolution :: struct {
     width:  i32,
@@ -184,7 +184,7 @@ game_render :: proc(game: ^Game) {
     render_game_to_window(game)
 
 
-	when DEBUG do rl.DrawFPS(10, rl.GetScreenHeight() - 20)
+	// when DEBUG do rl.DrawFPS(10, rl.GetScreenHeight() - 20)
     rl.EndDrawing()
 }
 

src/level_manager.odin

@@ -120,7 +120,7 @@ render_hud :: proc(level: Level) {
 
     p1_size := rl.MeasureTextEx(font, "PLAYER 1", HUD_FONT_SIZE, HUD_FONT_SPACING)
     p1_pos  := rl.Vector2{HUD_PADDING, HUD_PADDING}
-    rl.DrawTextEx(font, "PLAYER 1", p1_pos, HUD_FONT_SIZE, HUD_FONT_SPACING, rl.WHITE)
+    rl.DrawTextEx(font, "PLAYER", p1_pos, HUD_FONT_SIZE, HUD_FONT_SPACING, rl.WHITE)
 
     opp_size := rl.MeasureTextEx(font, "COMPUTER", HUD_FONT_SIZE, HUD_FONT_SPACING)
     opp_pos  := rl.Vector2{f32(VIEWPORT_W) - HUD_PADDING - opp_size.x, HUD_PADDING}
@@ -130,4 +130,4 @@ render_hud :: proc(level: Level) {
     score_size := rl.MeasureTextEx(font, score_text, HUD_FONT_SIZE, HUD_FONT_SPACING)
     score_pos  := rl.Vector2{(f32(VIEWPORT_W) * 0.5) - (score_size.x * 0.5), HUD_PADDING}
     rl.DrawTextEx(font, score_text, score_pos, HUD_FONT_SIZE, HUD_FONT_SPACING, rl.WHITE)
-}
+}

src/scene_manager.odin

@@ -251,7 +251,7 @@ render_main_menu :: proc(scene: Scene) {
     menu, menu_ok := canvas.menu.?
     assert(menu_ok, "render_main_menu: Canvas is missing a UI_Menu component")
 
-    t_text: cstring = "PONG"
+    t_text: cstring = WINDOW_TITLE
     t_width := rl.MeasureText(t_text, UI_TITLE_FONT_SIZE)
     t_x := i32(canvas.bounds.width * 0.5) - (t_width / 2)
     rl.DrawText(t_text, t_x, i32(canvas.padding), UI_TITLE_FONT_SIZE, rl.WHITE)