Pocket Putt Islands
README.md
flickShot 1.2.4
Drag-and-release / slingshot shot controls for any game: mini golf, pool, curling, paper toss, angry-birds style flings, basketball flicks, bocce. Put one FlickShot component on a physics ball (or call attach) and the player aims with touch, mouse or gamepad. You get a shot event with a world direction, a power 0..1 and an impulse in N·s, and the kit can push the body itself. Every look and behaviour switches with one setting: 8 aim styles, 8 power displays, 7 input modes, 10 feel presets and 4 looks. An optional ShotCam chase camera follows the ball, flies between holes and orbits behind a title screen.
It builds on the engine. Pointer, touch and pad come from the engine's input state (Zin.touch, Zin.state). Shots are real Physics.applyImpulse calls on the body's own rigid body. Screen-to-world aiming uses screenToRay, and bounce and laser previews use Physics.raycast. The kit adds the aiming feel, the visuals and the multiplayer rules.
Guides
Two guides ship inside the package. Open them with the guides tool or man:
- How to add drag-to-shoot slingshot controls to my game (
flickShot.package/guides/how-to-add-drag-to-shoot-slingshot-controls-to-my-game) - Example: build a paper toss game with drag-to-shoot (
flickShot.package/guides/example-build-a-paper-toss-game-with-drag-to-shoot)
Quick start
local Flick = require("flickShot.api")
local ball = entity.spawn("Ball", { position = { 0, 0.1, 0 } })
ball.localScale = { 0.2, 0.2, 0.2 }
ball.component.add("Model", { model = "sphere" })
ball.component.add("SphereCollider", {})
ball.component.add("Physics", { kind = "dynamic", mass = 0.05, linearDamping = 0.6 })
Flick.attach(ball, { preset = "golfPutt" }) -- drag back, release: it putts
Flick.onShot(function(shot)
print(shot.power, shot.direction, shot.impulse) -- vectors are Luau `vector`s
strokes += 1
end)
With no code at all, add flickShot.FlickShot to the ball in the inspector and pick a preset.
The public API (require("flickShot.api"))
| Call | What it does |
|---|---|
attach(entity, opts?) | Adds (or updates) the FlickShot on an entity. opts takes any component field and any preset field. Returns the component. |
detach(entity) | Removes it, along with its visuals. |
get(entity) | The FlickShot component, or nil. |
setStyle(entity, key, value) / setStyle(entity, { ... }) | Switches anything live: aimStyle, powerDisplay, inputMode, look, preset, grab, maxImpulse, ... |
configure(entity, overrides) | Code overrides for preset fields that have no component field (aimLength, chargePeriod, powerCurve, dragFraction, cancelRadius, rollDecel, cooldown, flickFullSpeed, minPower, restSpeed). |
setEnabled(entity, on) | Turns shooting on or off (sets canShoot). An aim in progress is cancelled. |
onShot(cb) | cb(shot) for every shot this peer takes. Returns an unsubscribe function. |
onAimStart(cb) / onCancel(cb) | cb({ entity, device }). Return unsubscribe functions. |
isAiming() / aimingEntity() | True or the entity while a player on this peer is aiming. Use it to block camera drags and other taps. |
shoot(entity, direction, power) | Fires from code (AI, replays, tests). |
settings(entity) / resolve(preset, overrides) | The settings in force, with the preset merged in. |
presets, aimStyles, powerDisplays, inputModes, looks, grabModes | Name lists. describe(name) gives one sentence about any of them. presetData / lookData hold the raw tables. |
The shot record (onShot, shoot): { entity, direction: vector (unit, world), power (0..1 as aimed), curvedPower (after the preset's curve), impulse: vector (N·s), impulseMagnitude, speed (m/s), mass, origin: vector, device ("touch" | "mouse" | "pad" | "demo" | "code"), inputMode, preset, applied (whether the kit pushed the body) }.
The component: flickShot.FlickShot
| Field | Default | Meaning |
|---|---|---|
preset | golfPutt | The feel preset. See the table below. |
aimStyle | preset | One of the aim styles, or preset to use the preset's choice. |
powerDisplay | preset | One of the power displays, or preset. |
inputMode | preset | dragBack, dragForward, holdCharge, flick, or preset. |
look | cartoon | cartoon, minimal, neon or pixel. |
grab | preset | ball (on it), near (within grabRadius points of its on-screen edge) or anywhere on screen. |
maxImpulse | 0 | N·s at full power. 0 means the preset's maxSpeed times the body's mass. |
maxSpeed | 0 | m/s at full power. 0 means the preset's value. |
loft | -1 | Degrees of launch tilt above the ground plane. -1 means the preset's value. |
canShoot | true | Turn it off between turns. (enabled is the engine's own switch for the whole component.) |
player | "" | Who may shoot it: a peer id, user id or player name. Empty means the peer that owns the entity. |
applyImpulse | true | The kit pushes the body. Off means only the shot event fires. |
waitForRest | true | Aim only while the body is nearly still. |
showOthersAim | true | Draw other players' aim, faint. |
showPercent | false | Add a % readout beside any power display. |
radius | 0 | The body radius used to place the visuals. 0 reads it from the entity's scale. |
aimScale | 1 | Size multiplier for the aim and power visuals only (the body radius still drives ray hits). 2 doubles them, which reads well on phones. |
demo / demoFires | false | Gallery mode: aims by itself in a loop when idle, and works in edit mode too. demoFires also shoots now and then while in play. |
Events: onShot { direction, power, curvedPower, impulse, speed, device }, onAimStart { device }, onCancel { device } (subscribe with comp.events.onShot:connect(fn)). Methods: configure(t), settings(), isAiming(), shoot(dir, power), cancel(), visualCount().
Aim styles (aimStyle)
| Style | What it draws |
|---|---|
dotted | A row of dots in the shot direction. More dots for a harder shot. |
arrow | A shaft with an arrow head that grows with power. |
rubberBand | A slingshot band from two fork points back to the pull point, thinning as it stretches. |
arc | The ballistic flight path, from speed, loft and the world's gravity. |
ghostBall | A ghost ball where a rolling shot stops (rollDecel) or a lofted one lands. |
laser | A thin beam to the first collider it hits, plus a hit marker. |
chevrons | Arrow heads marching along the line. More of them with power. |
bounceDots | Trajectory dots that predict one bounce off the first wall (a raycast and a reflection). |
Power displays (powerDisplay)
bar (over the ball, facing the camera), ring (beads around the ball), fill (the ball fills with colour and swells), segments (a meter from green to red), arc (a curved segmented meter beside the ball, green to red), pulse (the ball and a halo of beads pulse faster, wider and hotter as power rises), numeric (a %), none. Set showPercent = true to put a % beside any of them.
Input modes (inputMode)
| Mode | Touch / mouse | Gamepad |
|---|---|---|
dragBack | Press on or near the ball, pull back, release. The shot goes opposite the pull. | Left stick aims, hold A or RT to charge (ping-pong), release to fire, B cancels |
dragForward | Press and drag the way it should go | same |
holdCharge | Press and hold: the ball aims at the pointer, power charges (chargeMode = ramp or pingpong) | same, using the preset's charge mode |
flick | A quick swipe: the swipe's speed at release is the power | same |
dragAnywhere | A virtual thumbstick: press anywhere on screen, pull away from where the shot should go, release (stickFraction of the screen's shorter side is full power). For small or far balls | same |
meterTiming | Classic golf: drag back from the ball to aim, let go and a power meter swings (meterPeriod), tap anywhere to fire at that power | same |
tapTarget | Tap the spot to aim at: the ball is shot towards it with the power that carries it there (hold and slide to adjust) | same |
Cancel: slide back onto the ball, or onto the point you pressed (within cancelRadius points). The aim turns into a grey ring, and releasing there fires onCancel. A release weaker than minPower also cancels, and so does B on a pad. The mouse works exactly like touch. Touch wins when both are present, and the mouse is ignored for half a second after a touch. A press that lands on a UI widget never starts an aim.
Aim plane: plane = "ground" aims on the horizontal plane through the ball, tilted up by loft. plane = "screen" aims in the upright plane facing the camera, for side-on flings (slingshotFling). Direction comes from pointer rays hitting that plane, so aiming works with any camera, top-down or chase. Power is measured on screen (a full pull is dragFraction of the screen's shorter side), so it feels the same in phone portrait, landscape and desktop.
Feel presets (preset)
| Preset | Input | Aim | Power | Notes |
|---|---|---|---|---|
golfPutt | dragBack | dotted | ring | easeIn power, 7 m/s, waits for rest |
chipShot | dragBack | arc | bar | 38° loft, 8 m/s |
poolCue | dragBack (grab anywhere) | bounceDots | segments | 6 m/s |
curlingSlide | holdCharge (ramp 2.2 s) | ghostBall | bar | 5 m/s, low rolling deceleration |
paperToss | flick | arc | none | 45° loft, easeOut, grab anywhere |
slingshotFling | dragBack in the screen plane | rubberBand | fill | 14 m/s |
basketballFlick | flick | arc | ring | 55° loft, sCurve power |
classicSwing | meterTiming (1.1 s meter) | arrow | segments | 7 m/s |
thumbStick | dragAnywhere | chevrons | pulse | 7 m/s, grab anywhere |
bocceRoll | tapTarget | ghostBall | none | 6 m/s, rolls to the tapped spot |
Presets are data (presets.module). Any field can be overridden with a component field or configure. Power curves are linear, easeIn, easeOut and sCurve.
Looks (look)
cartoon (chunky, bright gradient), minimal (thin, white), neon (cyan, magenta and yellow), pixel (flat, blocky arrow heads). Each one is a colour set: aim, a low/mid/high power gradient, back, cancel and remote, plus line width and dot size. They are in Presets.looks, so add your own there.
Multiplayer
- Who aims: a peer drives only the shooters it controls. With
playerempty, that is the peer that owns the entity (entity.isLocal()). An unsynced entity is driven by every peer, which suits single player. Withplayerset, only the peer whose peer id, user id or player name matches drives it. Other peers never pick up presses on it. - Who applies the shot: the controlling peer calls
Physics.applyImpulseon the body. That peer owns and simulates the body, so the engine replicates the motion to everyone else, smoothed. Give each player's ball to its player: spawn it on their peer, ormultiplayer.claimOwnership(ball.id)from their peer. A peer never pushes a body it does not own. - Seeing others aim: while the owner aims, it writes a small synced value (
private.aim, at most 10 times a second, direction and power only). Other peers draw it as a faint dotted line whenshowOthersAimis on. - Events (
onShot,onAimStart,onCancel) fire on the shooting peer. Other peers see the ball move. Count shots from the syncedshotsvalue, or send your own message.
Mobile and cost
Visuals are pooled unlit primitives (spheres, cubes, cones and one Text3D label), with no shadows. They are spawned on first need and then only moved. A tint or visibility write costs about 25 times a transform write, so colours snap to eighths of power, and an unused piece shrinks to nothing before it is switched off. Measured on an Android phone: about 0.3 ms per shooter per frame while it draws, and nothing while idle. The worst style uses 28 pieces. comp:visualCount() reports the count. Nothing visual is synced. The grab radius (90 points) and cancel radius (34 points) are in UI points, so they keep finger size on every screen density.
Touch accuracy at lower render scale (phones and tablets)
Phones, tablets and lower quality settings draw the scene at less than full resolution (renderer.resolutionScale() below 1, about 0.75 on a typical tablet). The kit makes a finger on the ball (and the mouse) grab it on every engine and in every build. Engines differ in which pixels they report screen positions in:
- Today's engines: screen positions of things in the game (
worldToScreen,screenToRay,getViewportSize) come in render-scaled pixels while touches come in display pixels, so the kit multiplies every touch and mouse position by the render scale before it meets the camera. - Newer engines: these report every screen position in the same pixels as touches (and add a renderer call for the size the scene is rendered at). Scaling touches there would make the finger miss the ball, so they are used as they arrive.
Builds also differ in which pixels the mouse and touch arrive in: the Android app delivers both in displayed pixels, while a browser delivers the mouse in the projection's own pixels. So the kit never assumes a space. It measures it from the engine itself: ui.fromViewport (the engine's own mapping from pointer positions to UI points, the one that puts a press on the right button in every build) carried into projection pixels by getViewportSize() / ui.screenSize(). The ratio is the render scale where pointers arrive in displayed pixels and 1 where they arrive in projection pixels; a measurement within 4% of either snaps to it. No call's name or version number is involved. If that cannot be measured it compares getViewportSize() with the displayed size (ui.screenSize() x ui.pixelRatio("window")), then looks for a render-size call on the renderer, then uses the render scale.
Self-correcting press: if a press grabs nothing at the measured scale but lands on the player's own ball with the position taken as it is, or scaled by the render scale, the kit uses that and keeps it for the session (input.learnedMode). So even a build that maps pointers in a way the measurement misreads works from the first grab.
api.pointerScaleSource() says which path is in force ("measured" normally, "learned", "renderSize", "resolutionScale" or "override"), and api.pointerScale() the factor. api.setPointerScale(k) pins it, for example 1 when your own input already arrives in the camera's pixels; nil goes back to automatic. The test suite covers both engines with a stand-in renderer.
Known engine issues
These are engine problems, not kit bugs, and they stand until the engine fixes them:
- Issue 19356 (synced state on a device that was already running): a device that already had the engine running when a shared game was set up can end up seeing a different synced state from the other devices. For flickShot that touches only what other players see: the faint aim of another player (
showOthersAim, a synced value) and the syncedshotscount may be missing or out of date on that device. Your own aiming, shooting and your own ball are unaffected, because they run on your own device. Reloading the game on the affected device makes it join fresh. - Issue 26275 (frame rate on tablets): on an Android tablet the engine draws a scene like Pocket Putt Islands at about 24 to 26 frames a second (about 40 ms a frame, with occasional spikes near 90 ms), measured at the tablet's default render scale of 0.76. flickShot's own share of a frame is small (see "Mobile and cost"), and aiming reads the pointer every frame, so drags stay accurate at that rate; they just look less smooth than at 60.
Gallery
flickShot.gallery (zero scene load flickShot.gallery) shows every aim style, power display, look and preset as rows of balls that aim by themselves. In play, drag any ball to shoot it, and balls roll home a moment after they stop. The gallery stands at x = 80, so loading it as an additive layer beside your own scene does not overlap it.
Contents
FlickShot.component: the entry point.api.module: the public API.presets.module: presets, styles, looks and curves as data.shooter.module: the aim state machine and shot maths, with no engine state.input.module: pointer and pad sampling, the pointer space measurement (measuredScale,pointerScale,pointerScaleSource, the self-correctingretryPick, the fallbackrenderSizeCall) and shooter arbitration.ShotCam.componentandshotCam.module: an optional chase camera for the player's ball. It sits high and three-quarter behind the ball, faces a target (setTarget) or a heading (yaw), eases out while the player aims, sweeps between holes or turns withflyTo(target, duration), circles a point slowly withorbit(centre, { radius, height, speed })for a title or lobby backdrop (stopOrbit()ends it), widens its view on a portrait phone, and drives only the camera this peer owns in multiplayer.visuals.module: the pooled drawer.gallery.scene,flickShot.testSuite,guides/.
Tests: tools.use("tests", "run", { suite = "flickShot" }), run in edit mode.
Changes
- 1.2.4: documentation only. The README now opens with its title and version, documents all 10 presets, 7 input modes and 8 power displays (it listed 7, 4 and 7), and has a Known engine issues section (19356, 26275). The package description matches.
- 1.2.3: ShotCam
orbit(centre, opts)/stopOrbit()/isOrbiting()andshotCam.orbitPose, so a game's title backdrop needs no camera of its own. Three ShotCam maths tests. - 1.2.2: the mouse works in a browser at any window size. 1.2.1 scaled every pointer by the screen ratio it measured, but a browser delivers the mouse already in the projection's pixels, so the press landed up and to the left of the cursor and never grabbed the ball. The kit now measures the pointer space through the engine's own pointer -> UI mapping (
ui.fromViewport), and a press that misses at that scale is retried as-is and render-scaled, keeping whichever lands on the player's own ball. Four more tests. - 1.2.1: the old-or-new engine check no longer depends on what the new engine names its render-size call: the kit measures the space screen positions are reported in against the space touches arrive in, and scales touches only when they differ. A new engine whose call has an unexpected name now works too. Four more tests (unknown call name, older engine measured, snapping, live measurement).
- 1.2.0: touch and mouse aiming stay on the ball on newer engines that report screen positions in touch pixels. The kit detects the engine's render-size call and then stops scaling touches; on engines without it, the render scale correction from 1.1.1 stays as it was. New
api.pointerScaleSource(). NewShotCamchase camera component withshotCammaths (behind-the-ball follow, wider view on portrait phones, fly-to sweep). Four new tests for the pointer space on both kinds of engine. - 1.1.1: a finger on the ball grabs it first time when the scene renders below full resolution (touches carried into the render-scaled raster).
- 1.1.0: arc power display,
setEnabledsetscanShoot.