Polish gaming samples and expand the Game Development guide

- CasualGameSample: a juicy top-down arena -- thruster-flame ship, drifting
  asteroids, spinning gems, particle bursts, twinkling starfield -- with a
  safe-area anchored joystick.
- ScrollerGameSample: an animated runner (a six-frame walk cycle that flips to
  face its direction), a sun/cloud/hill parallax backdrop, jump on the stick-up
  or a JUMP button, and a world that re-lays-out on rotation.
- Gaming3DDemoSample: a spinning multi-cube monument on a textured grid ground,
  a ring of colored building Models scaled from one cube mesh, billboarded coins
  and trees, lit and orbited by a perspective camera.
- Game Development guide: add a three-sample showcase with screenshots, a new
  On-screen touch controls section (joystick/buttons + safe-area anchoring), a
  sprite-sheet walk-cycle illustration, a 3D screenshot, a Meshes and textures
  section, and a build-recipe "anatomy of a game".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: shai-almog

CodenameOne/src/com/codename1/gaming/VirtualJoystick.java

@@ -143,7 +143,6 @@ private void moveTo(float px, float py) {
         if (dist > radius && dist > 0) {
             dx = dx / dist * radius;
             dy = dy / dist * radius;
-            dist = radius;
         }
         knobX = centerX + dx;
         knobY = centerY + dy;

Samples/samples/CasualGameSample/CasualGameSample.java

@@ -4,10 +4,12 @@
 import com.codename1.gaming.GameView;
 import com.codename1.gaming.Model;
 import com.codename1.gaming.Sprite;
+import com.codename1.gaming.TouchControls;
 import com.codename1.gpu.GraphicsDevice;
 import com.codename1.gpu.Material;
 import com.codename1.gpu.Mesh;
 import com.codename1.gpu.Primitives;
+import com.codename1.gpu.Texture;
 import com.codename1.io.Log;
 import com.codename1.ui.Display;
 import com.codename1.ui.Form;
@@ -56,70 +58,114 @@ public void destroy() {
 
     /// The 3D game surface.
     static class World3DView extends GameView {
-        private static final int COIN_COUNT = 8;
-        private static final float COIN_RING = 4f;
+        private static final int COIN_COUNT = 10;
+        private static final float COIN_RING = 5f;
+        private static final int BUILDINGS = 8;
 
-        private Model cube;
+        private final Model[] monument = new Model[3];
+        private final Sprite[] coins = new Sprite[COIN_COUNT];
         private double time;
         private double orbit;
-        private float camHeight = 6f;
+        private float camHeight = 7f;
         private boolean controlsReady;
 
         World3DView() {
-            setClearColor(0xff101824);
-            // perspective camera looking at the cube from above and behind
+            setClearColor(0xff1a2a4a);   // dusk sky
             getCamera()
-                    .setPerspective(60f, 0.1f, 200f)
-                    .setPosition(0f, 6f, 12f)
-                    .setTarget(0f, 1f, 0f);
+                    .setPerspective(60f, 0.1f, 300f)
+                    .setPosition(0f, 7f, 15f)
+                    .setTarget(0f, 2.5f, 0f);
 
-            // a ring of billboarded coins in 3D world space
+            // a ring of billboarded coins floating in 3D world space
             Image coinImage = makeCoin(48, 0xffffd54a);
             for (int i = 0; i < COIN_COUNT; i++) {
                 double a = i * 2 * Math.PI / COIN_COUNT;
-                Sprite coin = new Sprite(coinImage);
-                coin.setPosition(Math.cos(a) * COIN_RING, 1.2, Math.sin(a) * COIN_RING);
-                coin.setSize(1.2f, 1.2f);   // world units, not pixels
-                getScene().add(coin);
+                coins[i] = new Sprite(coinImage);
+                coins[i].setPosition(Math.cos(a) * COIN_RING, 1.4, Math.sin(a) * COIN_RING);
+                coins[i].setSize(1.1f, 1.1f);   // world units, not pixels
+                getScene().add(coins[i]);
+            }
+            // a few billboarded trees for scenery (always face the camera)
+            Image treeImage = makeTree(72);
+            double[] tx = {-11, 10, -9, 12, 2};
+            double[] tz = {-10, -8, 9, 7, -13};
+            for (int i = 0; i < tx.length; i++) {
+                Sprite tree = new Sprite(treeImage);
+                tree.setPosition(tx[i], 1.8, tz[i]);
+                tree.setSize(3.6f, 3.6f);
+                getScene().add(tree);
             }
         }
 
         protected void onSetup(GraphicsDevice device) {
-            // ground plane: a quad rotated flat, lit and green
-            Mesh quad = Primitives.quad(device, 16f);
-            Material grass = new Material(Material.Type.LAMBERT).setColor(0xff2f7d32);
-            Model ground = new Model(quad, grass);
+            // textured grid ground: a quad rotated flat, lit and tinted green
+            Mesh groundMesh = Primitives.quad(device, 64f);
+            Texture grid = device.createTexture(makeGrid(256, 0xffe8efe8, 0xff9fc0a0, 8));
+            Material groundMat = new Material(Material.Type.LAMBERT)
+                    .setColor(0xff3f7d4f).setTexture(grid);
+            Model ground = new Model(groundMesh, groundMat);
             ground.setRotation(-90f, 0f, 0f);   // XY quad -> horizontal XZ ground
             addModel(ground);
 
-            // a gold spinning cube sitting on the ground
-            Mesh cubeMesh = Primitives.cube(device, 2f);
-            Material gold = new Material(Material.Type.PHONG).setColor(0xffffcc33).setShininess(32f);
-            cube = new Model(cubeMesh, gold);
-            cube.setPosition(0f, 1f, 0f);
-            addModel(cube);
+            // central spinning monument: three stacked, shiny cubes
+            Mesh cubeMesh = Primitives.cube(device, 1f);
+            int[] mcol = {0xffffcc33, 0xff33c7c7, 0xffff7043};
+            float[] msize = {2.6f, 1.7f, 1.0f};
+            float y = 0f;
+            for (int i = 0; i < 3; i++) {
+                y += msize[i] / 2f;
+                Material m = new Material(Material.Type.PHONG).setColor(mcol[i]).setShininess(24f);
+                Model c = new Model(cubeMesh, m);
+                c.setScale(msize[i]);
+                c.setPosition(0f, y, 0f);
+                monument[i] = c;
+                addModel(c);
+                y += msize[i] / 2f;
+            }
+
+            // a ring of colored "buildings" of varying height (one cube mesh, scaled)
+            int[] bcol = {0xff5b8def, 0xffe06ca0, 0xff8bd450, 0xfff2b134,
+                0xff9b6cf0, 0xff4fd1c5, 0xffef6f6f, 0xffb0bec5};
+            for (int i = 0; i < BUILDINGS; i++) {
+                double a = i * 2 * Math.PI / BUILDINGS;
+                float h = 1.6f + (i % 4) * 0.9f;
+                Material m = new Material(Material.Type.LAMBERT).setColor(bcol[i % bcol.length]);
+                Model b = new Model(cubeMesh, m);
+                b.setScale(1.5f, h, 1.5f);
+                b.setPosition((float) (Math.cos(a) * 9.5), h / 2f, (float) (Math.sin(a) * 9.5));
+                addModel(b);
+            }
 
-            getLight().setDirection(-0.5f, -1f, -0.4f).setColor(0xffffffff).setAmbientColor(0xff404048);
+            getLight().setDirection(-0.4f, -1f, -0.3f).setColor(0xfffff4e0)
+                    .setAmbientColor(0xff3a4257);
         }
 
         protected void update(double dt) {
             time += dt;
-            if (cube != null) {
-                cube.setRotation(0f, (float) (time * 60), 0f);   // spin around Y
+            // each monument tier spins at its own speed and direction
+            for (int i = 0; i < monument.length; i++) {
+                if (monument[i] != null) {
+                    float dir = (i % 2 == 0) ? 1f : -1f;
+                    monument[i].setRotation(0f, (float) (time * (30 + i * 22)) * dir, 0f);
+                }
+            }
+            // bob the coins up and down
+            for (int i = 0; i < COIN_COUNT; i++) {
+                coins[i].setY(1.4 + Math.sin(time * 2 + i) * 0.3);
             }
             if (!controlsReady && getWidth() > 0) {
-                getControls().addJoystick(110, getHeight() - 110, 80);
+                getControls().addJoystick(80, TouchControls.LEFT, TouchControls.BOTTOM, 30);
                 controlsReady = true;
             }
             // the joystick orbits the camera (x) and raises/lowers it (y); when
-            // untouched the camera drifts on its own.
+            // untouched the camera drifts slowly on its own.
             float ax = getInput().getAxisX();
             float ay = getInput().getAxisY();
-            orbit += (ax != 0 ? ax * 1.5 : 0.3) * dt;
-            camHeight = clamp(camHeight + ay * 6f * (float) dt, 1.5f, 14f);
-            float r = 12f;
+            orbit += (ax != 0 ? ax * 1.5 : 0.25) * dt;
+            camHeight = clamp(camHeight + ay * 7f * (float) dt, 2.5f, 18f);
+            float r = 15f;
             getCamera().setPosition((float) (Math.sin(orbit) * r), camHeight,
-                    (float) (Math.cos(orbit) * r));
+                    (float) (Math.cos(orbit) * r)).setTarget(0f, 2.5f, 0f);
         }
 
         private static float clamp(float v, float lo, float hi) {
@@ -138,4 +184,34 @@ static Image makeCoin(int size, int color) {
         g.fillArc(size / 4, size / 5, size / 3, size / 3, 0, 360); // highlight
         return img;
     }
+
+    /// Builds a grid texture (a base fill crossed by `cells` evenly spaced lines each
+    /// way) used to tint and detail the ground so the 3D space reads with depth.
+    static Image makeGrid(int size, int baseColor, int lineColor, int cells) {
+        Image img = Image.createImage(size, size, baseColor);
+        Graphics g = img.getGraphics();
+        g.setColor(lineColor);
+        int step = size / cells;
+        for (int i = 0; i <= cells; i++) {
+            int p = Math.min(size - 2, i * step);
+            g.fillRect(p, 0, 2, size);   // vertical line
+            g.fillRect(0, p, size, 2);   // horizontal line
+        }
+        return img;
+    }
+
+    /// Builds a simple billboard tree (brown trunk, layered green canopy) on a
+    /// transparent background.
+    static Image makeTree(int size) {
+        Image img = Image.createImage(size, size, 0);
+        Graphics g = img.getGraphics();
+        g.setAntiAliased(true);
+        g.setColor(0xff7a4a26);
+        g.fillRect(size / 2 - size / 14, size * 3 / 5, size / 7, size * 2 / 5); // trunk
+        g.setColor(0xff2f8f3f);
+        g.fillArc(size / 6, size / 5, size * 2 / 3, size * 2 / 3, 0, 360);       // canopy
+        g.setColor(0xff3fa84f);
+        g.fillArc(size / 4, size / 8, size / 2, size / 2, 0, 360);               // highlight
+        return img;
+    }
 }