Overview

neoCanvas is a native 2D canvas for VisualNEO Win. It combines sprites, sprite-sheet animation, vector drawing, particles, basic physics and collisions, keyboard input, and low-latency sound effects in one control. It is intended for arcade games, interactive diagrams, animated interfaces, and other frame-driven publications.

Rendering uses GDI+ antialiasing and an off-screen buffer. Sound effects use Windows DirectSound 8 and require no additional runtime DLL.

Properties

Property	Type	Default	Purpose
`fps`	integer	`60`	Fixed simulation rate from 1 to 60 FPS.
`physicsGravityY`	number	`0.0`	Vertical acceleration applied to sprites.
`physicsFriction`	number	`0.99`	Velocity multiplier applied by the scene.
`enableClickSelection`	boolean	`true`	Enables `spriteclick`.
`keyboardEnabled`	boolean	`true`	Enables keyboard state and keyboard events.
`autoFocus`	boolean	`true`	Gives the canvas keyboard focus when clicked.
`emitTickEvents`	boolean	`true`	Enables the frame `tick` event. Disable it when it is not needed.
`tickEventFps`	integer	`10`	Limits NeoScript `tick` delivery independently from rendering FPS (1 to 60). Use a low rate for action-heavy game logic.
`masterSfxVolume`	integer	`100`	Sound-effects volume from 0 to 100.
`maxSoundVoices`	integer	`32`	Maximum simultaneous DirectSound voices, from 1 to 128.
`bgColor`	color/string	`auto`	Canvas background color, `auto`, or `transparent`.

The VisualNEO style panel also supplies the host fill, line color, line width, and Hollow state.

Keyboard And Game Loop

Click the canvas or call neoCanvasFocus before expecting keyboard input. Multiple keys remain active at the same time. The state is cleared automatically when the control loses focus, is disabled, is hidden, or is destroyed, preventing a movement key from becoming stuck.

Use keydown for discrete commands such as firing or opening a menu. Use neoCanvasIsKeyDown or the pressedKeys array during tick for continuous movement. This avoids depending on the Windows key-repeat delay.

tick supplies:

deltaTime: real elapsed time in seconds, capped after long pauses.
fixedDelta: stable simulation step, normally 1 / fps.
frame: monotonically increasing simulation frame number.
fps: configured target rate.

The engine performs at most five catch-up updates per timer message so a suspended page cannot produce an uncontrolled update burst.

Actions

Scene And Drawing

Command	Parameters after object name	Result or purpose
`neoCanvasClear`	none	Removes every sprite, shape, and particle.
`neoCanvasSetBackground`	color or image path	Sets a `#HEX` color, `auto`, `transparent`, or BMP image.
`neoCanvasDrawLine`	X1, Y1, X2, Y2, color, width	Adds an antialiased line.
`neoCanvasDrawCircle`	center X, center Y, radius, fill, stroke	Adds a circle.
`neoCanvasDrawText`	text, X, Y, font, size, color	Adds text.
`neoCanvasDrawRectangle`	X, Y, width, height, fill, stroke, line width, corner radius	Adds a rectangle.
`neoCanvasDrawEllipse`	center X, center Y, radius X, radius Y, fill, stroke, line width	Adds an ellipse.
`neoCanvasDrawStar`	center X, center Y, points, outer radius, inner radius, fill, stroke, line width	Adds a star or regular polygon.
`neoCanvasDrawPolyline`	point list, color, width	Adds a path such as `10,10,50,20,80,5`.
`neoCanvasDrawPoint`	X, Y, color, radius	Adds a smooth point.
`neoCanvasEmitParticles`	preset, X, Y, count, optional colors	Emits `confetti`, `fireworks`, `snow`, `rain`, `magic`, `fire`, or `explosion`.
`neoCanvasExportImage`	output path	Saves the rendered scene as PNG or BMP.
`neoCanvasGetPixel`	X, Y, result variable	Returns the rendered pixel as `#RRGGBB`.

Sprites And Collisions

Command	Parameters after object name	Result or purpose
`neoCanvasAddSprite`	sprite ID, BMP path, X, Y, width, height	Adds a sprite. The image path may be empty for an invisible collision entity.
`neoCanvasAddAnimatedSprite`	sprite ID, sheet path, X, Y, frame width, frame height, frame count, FPS	Adds a sprite-sheet animation.
`neoCanvasMoveSprite`	sprite ID, X, Y, optional velocity X, velocity Y	Sets position and optionally velocity.
`neoCanvasRotateSprite`	sprite ID, degrees	Sets rotation.
`neoCanvasScaleSprite`	sprite ID, scale X, scale Y	Sets visual scale.
`neoCanvasFlipSprite`	sprite ID, horizontal, vertical	Flips the image.
`neoCanvasSetSpriteAnim`	sprite ID, playing, frame, loop	Controls animation playback.
`neoCanvasSetSpriteZIndex`	sprite ID, Z index	Changes draw order.
`neoCanvasEnableSpriteDrag`	sprite ID, enabled	Enables pointer dragging.
`neoCanvasSetSpriteSolid`	sprite ID, solid, restitution	Enables simple solid/bounce behavior.
`neoCanvasSetSpriteVisible`	sprite ID, visible	Shows or hides a sprite without removing it. Hidden sprites do not collide.
`neoCanvasSetSpriteGroup`	sprite ID, group	Adds a logical group to collision event data.
`neoCanvasGetSpriteState`	sprite ID, result variable	Returns position, velocity, size, angle, visibility, group, frame, and playback state as JSON.
`neoCanvasCheckCollision`	sprite A, sprite B, result variable	Returns `True` or `False`.
`neoCanvasCheckGroupCollision`	sprite ID, group, matching sprite variable, result variable	Tests one sprite against every visible sprite in a group and returns the first matching sprite ID plus `True` or `False`.
`neoCanvasConsumeGroupCollision`	sprite ID, group, matching sprite variable, result variable	Consumes a native collision-start record retained since the previous logic tick. Fast contacts cannot pass unnoticed.
`neoCanvasPointInSprite`	sprite ID, X, Y, result variable	Returns `True` or `False`.
`neoCanvasRemoveSprite`	sprite ID	Removes the sprite.

Input

Command	Parameters after object name	Result or purpose
`neoCanvasFocus`	none	Moves keyboard focus to the canvas.
`neoCanvasIsKeyDown`	key name/code, result variable	Returns `True` while that key is held. Names include `Left`, `Right`, `Up`, `Down`, `Space`, `Enter`, `Escape`, letters, digits, and `F1` to `F24`.
`neoCanvasConsumeKeyPress`	key name/code, result variable	Returns `True` once for each initial press retained by the native input queue, even if the key was released before NeoScript polls it.
`neoCanvasGetInputState`	result variable	Returns `focused` and the `pressedKeys` code array as JSON.

Sound Effects

Command	Parameters after object name	Result or purpose
`neoCanvasLoadSound`	sound ID, WAV path	Preloads a PCM WAV file.
`neoCanvasPlaySound`	sound ID, volume, pan, pitch, loop, voice variable	Starts a new simultaneous voice and returns an ID such as `laser#3`.
`neoCanvasStopSound`	sound or voice ID	Stops one voice or every voice using a sound ID; returns the count.
`neoCanvasPauseSound`	sound or voice ID	Pauses matching voices; returns the count.
`neoCanvasResumeSound`	sound or voice ID	Resumes matching voices; returns the count.
`neoCanvasUnloadSound`	sound ID	Stops matching voices and releases the preloaded asset.
`neoCanvasStopAllSounds`	none	Stops every voice on this canvas.
`neoCanvasSetMasterVolume`	0 to 100	Changes the volume of active and future voices.

Sound effects accept uncompressed PCM RIFF/WAV files. Convert MP3, AAC, floating-point WAV, and compressed WAV files to PCM WAV first. Each neoCanvasPlaySound call creates an independent voice, so repeated shots and impacts can overlap. Use neoAudio for music, streaming, and long-form playback.

Events

Event	Payload	Notes
`tick`	`fps`, `deltaTime`, `fixedDelta`, `frame`	Stable game-loop timing.
`keydown`	`keyCode`, `key`, `repeat`, modifiers, `pressedKeys`	Fires for initial press and Windows repeats.
`keyup`	same keyboard payload	Fires on release.
`inputchange`	keyboard payload or `reason: focusLost`	Fires only when held-key state changes.
`spriteclick`	`spriteId`, `x`, `y`	Sprite pointer click.
`spritedragstart`	`spriteId`, `x`, `y`	Drag begins.
`spritedragging`	`spriteId`, `x`, `y`	Drag position changes.
`spritedrop`	`spriteId`, `x`, `y`	Drag ends.
`spritehoverenter`	`spriteId`, `x`, `y`	Pointer enters a sprite.
`spritehoverleave`	`spriteId`, `x`, `y`	Pointer leaves a sprite.
`collisionenter`	sprite IDs and groups	Fires once when a pair starts intersecting.
`collisionexit`	sprite IDs and groups	Fires once when a pair separates.
`collision`	sprite IDs and groups	Compatibility event; now fires once with `collisionenter`.
`particleend`	empty object	Fires when the active particle list becomes empty.
`soundend`	`soundId`, `voiceId`	Fires when a non-looping voice completes naturally.

Minimal Game Pattern

TEXT

neoCanvasFocus "GameCanvas"
neoCanvasLoadSound "GameCanvas" "laser" "[PubDir]assets/laser.wav"
neoCanvasAddSprite "GameCanvas" "player" "[PubDir]assets/player.bmp" "140" "190" "32" "24"
neoCanvasSetSpriteGroup "GameCanvas" "player" "players"

In the tick event, query Left and Right with neoCanvasIsKeyDown, calculate the next X position, and call neoCanvasMoveSprite. In keydown, play the laser only when keyCode is 32 (Space) and repeat is false. Handle collisionenter to remove targets and play impact sounds.

Playable Sample

Open samples/neoCanvas-invaders-demo.pub to run a complete mini-game built with ordinary VisualNEO actions and one neoCanvas control. Its local assets folder contains all required BMP sprites and PCM WAV effects.

The sample demonstrates:

Native 60 FPS sprite movement for the player, invader formation, and projectile, while NeoScript gameplay is throttled to 6 tick events per second.
Simultaneous arrow-key, A/D, and Space state queried with neoCanvasIsKeyDown.
Native queued Space and R presses consumed exactly once, including short taps that begin and end between NeoScript ticks.
A fast eight-sprite formation whose native velocity is reversed at each edge, descends toward the player, and ends the round if it reaches the defensive line.
A reusable four-projectile pool with smooth native movement and queued group collisions through neoCanvasConsumeGroupCollision, preventing fast projectiles from tunneling between logic ticks.
Score and status variables displayed by ordinary VisualNEO text objects.
A live score and elapsed-time panel refreshed from NeoScript.
Dedicated game-over and victory screens with final score, completion time, particles, and sound.
Explosion and fireworks particles plus overlapping laser, hit, and victory effects.
Small, reusable NeoScript subroutines named ResetGame, MoveLeft, MoveRight, Fire, ProcessShot1 to ProcessShot4, and UpdateFleet.
Dot-prefixed NeoScript comments explaining scene setup, the projectile pool, movement, recycling, collisions, scoring, and final states.

Inspect the GameCanvas Actions panel to see the tick handler, including the R and Space key latches. Inspect the publication subroutines to see scene creation, movement, firing, hit processing, HUD refresh, final screens, and sound logic. The mouse buttons call the same movement, fire, and restart subroutines used by the keyboard path.

Deployment

Install the complete com.visualneo.neocanvas.vnplugin folder. The Win32 module is bin/win32-x86/neoCanvas.dll. No third-party DLL or audio codec package is required.