Enhance physics materials, collision detection, and example projects

README.md

@@ -75,7 +75,7 @@ composer require sendamaphp/engine
 ```
 
 ## Usage
-See [examples](examples/EXAMPLES.md) and [Documentation](docs/DOCS.md).
+See [examples](examples/EXAMPLES.md), [Documentation](docs/DOCS.md), and the [Collision Detection Guide](docs/Collision.md).
 
 ## Notes
 The examples in [examples]() are made to demonstrate how Sendama may be used to make simple 2D games.

composer.json

@@ -25,7 +25,7 @@
         }
     ],
     "require": {
-        "php": "^8.3",
+        "php": "^8.4",
         "assegaiphp/collections":  "^0.3.2",
         "amasiye/figlet":  "^1.2",
         "vlucas/phpdotenv": "^5.6",

docs/Collision.md

@@ -0,0 +1,94 @@
+# Collision Detection Guide
+
+This guide shows the basic collision workflow in Sendama and how to swap collision strategies when you need different behavior.
+
+## Quick Setup
+
+1. Add a collider component to the game object before you add it to a scene.
+2. Give the object a sprite, because collider bounds are derived from the sprite rectangle.
+3. Move the object with `CharacterController` if you want movement to stop on solid collisions.
+4. Handle collision callbacks in a behaviour.
+
+```php
+<?php
+
+use Sendama\Engine\Core\Behaviours\Behaviour;
+use Sendama\Engine\Core\GameObject;
+use Sendama\Engine\Core\Vector2;
+use Sendama\Engine\Physics\CharacterController;
+use Sendama\Engine\Physics\Interfaces\CollisionInterface;
+
+final class PlayerCollisionHandler extends Behaviour
+{
+  public function onCollisionEnter(CollisionInterface $collision): void
+  {
+    echo 'Hit ' . $collision->getGameObject()->getName();
+  }
+}
+
+$player = new GameObject('Player');
+$player->setSpriteFromTexture('Textures/player.texture', Vector2::zero(), Vector2::one());
+$player->addComponent(CharacterController::class);
+$player->addComponent(PlayerCollisionHandler::class);
+```
+
+## Built-in Strategies
+
+- `AABBCollisionDetectionStrategy`: compares bounding boxes. This is the default for `Collider`, `CharacterController`, and `Rigidbody`.
+- `SimpleCollisionDetectionStrategy`: currently uses the same bounding-box overlap check, but without the extra debug logging.
+- `BasicCollisionDetectionStrategy`: only reports a hit when two colliders share the exact same position.
+- `SeparationBasedCollisionDetectionStrategy`: reports a hit when the distance between colliders is less than `1`.
+
+## Changing a Strategy
+
+Use `setCollisionDetectionStrategy()` on the collider component instance itself. In practice that means a `Collider`, `CharacterController`, or `Rigidbody`, because those are the components that implement `ColliderInterface`.
+
+```php
+<?php
+
+use Sendama\Engine\Physics\CharacterController;
+use Sendama\Engine\Physics\Strategies\BasicCollisionDetectionStrategy;
+
+/** @var CharacterController $controller */
+$controller = $player->addComponent(CharacterController::class);
+$controller->setCollisionDetectionStrategy(
+  new BasicCollisionDetectionStrategy($controller)
+);
+```
+
+## Solid vs Trigger Colliders
+
+- Solid colliders block `CharacterController::move()`.
+- Trigger colliders do not block movement.
+- To make a pickup or checkpoint a trigger, call `setTrigger(true)`.
+
+```php
+$coinCollider->setTrigger(true);
+```
+
+At the moment, the `CharacterController` path dispatches `onCollisionEnter()` and `onCollisionStay()` for both solid and trigger contacts, so those are the safest callbacks to implement for gameplay reactions.
+
+## Manual Collision Checks
+
+If you want to query collisions yourself:
+
+```php
+<?php
+
+use Sendama\Engine\Core\Vector2;
+use Sendama\Engine\Physics\Physics;
+
+$collisions = Physics::getInstance()->checkCollisions($playerCollider, new Vector2(1, 0));
+
+if ($collisions !== []) {
+  // The move would overlap another collider.
+}
+```
+
+`checkCollisions()` tests the collider's projected bounds after applying the motion vector, which is useful for predicting whether a move will be blocked before translating the object.
+
+## Notes
+
+- Colliders are registered with physics when the game object is added to the scene.
+- If you add a collider after the object is already running, register it with `Physics::getInstance()->addCollider(...)` yourself.
+- Collision bounds come from the game object's sprite rect, so a missing sprite means unreliable collision bounds.

docs/DOCS.md

@@ -19,8 +19,9 @@
     - [Removing a Scene](#removing-a-scene)
   - [Game Objects](#game-objects)
     - [Creating a Game Object](#creating-a-game-object)
-    - [Moving a Game Object](#moving-a-game-object)
+  - [Moving a Game Object](#moving-a-game-object)
   - [Components](#components)
+- [Collision Detection Guide](Collision.md)
 
 ## Introduction
 Sendama is a 2D game engine for terminal based games. It is written in PHP and is designed to be easy to use and extend. It is a work in progress and is not yet ready for production use.
@@ -181,4 +182,4 @@ use \Sendama\Engine\Core\Scenes\SceneManager;
 SceneManager::getInstance()->addScene($scene);
 ```
 
-#### Removing a Scene
+#### Removing a Scene

examples/blasters/assets/Scenes/Level01.php

@@ -6,7 +6,7 @@
 use Sendama\Engine\Core\GameObject;
 use Sendama\Engine\Core\Scenes\AbstractScene;
 use Sendama\Engine\Core\Sprite;
-use Sendama\Engine\Core\Texture2D;
+use Sendama\Engine\Core\Texture;
 use Sendama\Engine\Core\Vector2;
 use Sendama\Examples\Blasters\Scripts\Game\LevelManager;
 use Sendama\Examples\Blasters\Scripts\Player\WeaponManager;
@@ -37,7 +37,7 @@ public function awake(): void
 
     $playerStartingX = 4;
     $playerStartingY = $screenHeight / 2;
-    $playerTexture = new Texture2D('Textures/player.texture');
+    $playerTexture = new Texture('Textures/player.texture');
     $player->setSpriteFromTexture($playerTexture, new Vector2(0, 1), new Vector2(5, 3));
     $player->getTransform()->setPosition(new Vector2($playerStartingX, $playerStartingY));
     /**

examples/blasters/config/input.php

@@ -0,0 +1,4 @@
+<?php
+
+return [];
+

examples/blasters/preferences.json

@@ -0,0 +1,2 @@
+{}
+

examples/collector/assets/Scenes/Level01.php

@@ -6,7 +6,7 @@
 use Sendama\Engine\Core\GameObject;
 use Sendama\Engine\Core\Scenes\AbstractScene;
 use Sendama\Engine\Core\Sprite;
-use Sendama\Engine\Core\Texture2D;
+use Sendama\Engine\Core\Texture;
 use Sendama\Engine\Core\Vector2;
 use Sendama\Engine\Physics\CharacterController;
 use Sendama\Engine\Physics\Collider;
@@ -36,12 +36,12 @@ public function awake(): void
     $apple = new GameObject(Name::APPLE->value);
 
     // GUI Elements
-    $collectedLabel = new Label($this, 'Collected Label', new Vector2(0, 27), new Vector2(15, 1));
-    $collected = 0;
-    $collectedLabel->setText(sprintf("%-12s %03d", 'Collected: ',$collected));
-
-    $stepsLabel = new Label($this, 'Steps Label', new Vector2(65, 27), new Vector2(15, 1));
-    $stepsLabel->setText(sprintf("%-9s %06d", 'Steps: ', 0));
+//    $collectedLabel = new Label($this, 'Collected Label', new Vector2(0, 27), new Vector2(15, 1));
+//    $collected = 0;
+//    $collectedLabel->setText(sprintf("%-12s %03d", 'Collected: ',$collected));
+//
+//    $stepsLabel = new Label($this, 'Steps Label', new Vector2(65, 27), new Vector2(15, 1));
+//    $stepsLabel->setText(sprintf("%-9s %06d", 'Steps: ', 0));
 
     // Set up the level manager
     $levelManager->addComponent(LevelManager::class);
@@ -56,7 +56,7 @@ public function awake(): void
 
     $playerStartingX = 4;
     $playerStartingY = $screenHeight / 2;
-    $playerTexture = new Texture2D('Textures/player.texture');
+    $playerTexture = new Texture('Textures/player.texture');
     $player->getTransform()->setPosition(new Vector2($playerStartingX, $playerStartingY));
     /**
      * @var CharacterMovement $playerMovementController
@@ -73,7 +73,7 @@ public function awake(): void
     $player->setSpriteFromTexture($playerTexture, Vector2::zero(), Vector2::one());
 
     // Set up the apple
-    $appleTexture = new Texture2D('Textures/apple.texture');
+    $appleTexture = new Texture('Textures/apple.texture');
     $apple->addComponent(CollectableController::class);
     $apple->addComponent(Collider::class);
     $apple->setSpriteFromTexture($appleTexture, Vector2::zero(), Vector2::one());
@@ -82,7 +82,5 @@ public function awake(): void
     $this->add($levelManager);
     $this->add($player);
     $this->add($apple);
-    $this->add($collectedLabel);
-    $this->add($stepsLabel);
   }
 }

examples/collector/assets/Scenes/SettingsScene.php

@@ -7,6 +7,7 @@
 use Sendama\Engine\Core\GameObject;
 use Sendama\Engine\Core\Rect;
 use Sendama\Engine\Core\Scenes\AbstractScene;
+use Sendama\Engine\Core\Scenes\SceneManager;
 use Sendama\Engine\Core\Vector2;
 use Sendama\Engine\Debug\Debug;
 use Sendama\Engine\UI\Menus\Menu;
@@ -29,9 +30,13 @@ public function awake(): void
     $settingsMenuWidth = 30;
     $settingsMenuHeight = DEFAULT_MENU_HEIGHT;
 
+    $sceneManager = SceneManager::getInstance();
+    $screenWidth = $sceneManager->getSettings('screen_width') ?? DEFAULT_SCREEN_WIDTH;
+    $screenHeight = $sceneManager->getSettings('screen_height') ?? DEFAULT_SCREEN_HEIGHT;
+
     Debug::log(var_export($this->settings, true));
-    $leftMargin = round(DEFAULT_SCREEN_WIDTH / 2 - $settingsMenuWidth / 2);
-    $topMargin = round(DEFAULT_SCREEN_HEIGHT / 2 - $settingsMenuHeight / 2);
+    $leftMargin = round($screenWidth / 2 - $settingsMenuWidth / 2);
+    $topMargin = round($screenHeight / 2 - $settingsMenuHeight / 2);
     $settingsMenuBorderPack = new BorderPack(Path::join(Path::getVendorAssetsDirectory(), 'border-packs', 'slim.border.php'));
 
     $settingsPosition = new Vector2($leftMargin, $topMargin);
@@ -53,4 +58,4 @@ public function awake(): void
     $this->add($levelManager);
     $this->add($settingsMenu);
   }
-}
+}

examples/collector/assets/Scripts/Collectable/CollectableController.php

@@ -32,7 +32,16 @@ class CollectableController extends Behaviour
   #[Override]
   public function onStart(): void
   {
-    $this->getGameObject()->addComponent(Collider::class);
+    $collider = $this->getComponent(Collider::class);
+
+    if (!$collider) {
+      $collider = $this->getGameObject()->addComponent(Collider::class);
+    }
+
+    if ($collider instanceof Collider) {
+      $collider->setTrigger(true);
+    }
+
     $this->randomizePosition();
 
     if ($levelManagerGO = GameObject::find(Name::LEVEL_MANAGER->value))
@@ -70,4 +79,4 @@ protected function randomizePosition(): void
         )
       );
   }
-}
+}