Commodore‎ > ‎BASIC‎ > ‎Keywords‎ > ‎


Keyword Abbreviation Token (hex) Version(s) Classification
MOVSPR M{Shift+O} FE 06 7.0 Command and Statement

MOVSPR sprite , { { xVal yVal } | {  distance ; angle } | { angle # speed }
Parameters Type Legal Value(s) Default Value Note(s)
sprite Unsigned Byte 1 ~ 8

xVal Signed Integer -32768 ~ 32767   a literal + or - invokes relative ordinate
yVal Signed Integer -32768 ~ 32767
a literal + or - invokes relative ordinate
angle Signed Integer -32768 ~ 32767   in degrees (clockwise); relative to "up" = 0
distance Signed Integer -32768 ~ 32767    in pixels [because VIC pixels are not square, the angle is important]
speed Signed Integer -32768 ~ 32767    should be 0 to 15 
Sprite state management.  Position a sprite or start/stop a sprite's motion.

MOVSPR allows you to either set the current positon of a SPRITE or set its motion.  Setting the postion of a sprite which is already in motion will be temporary; it will automatically be moved from the new location within a jiffy (based on the previously set direction and speed).
All SPRITEs' positions are intitialized (to 0,0) only on BASIC power-up; the SPRITEs' speed are initialized to zero (no movement) on power-up and STOP+RESTORE.  In particular, none of the SPRITEs' position/motion is reset when a program is RUN.  So be sure to use MOVSPR to stop sprite movement in any program using SPRITEs.  (Of course you will probably want to use MOVSPR to set their initial position too.)  SPRDEF (not very common) will set an edited sprite's position to (264,74) and its speed  to zero (other, non-edited sprites, will remain at their previous location/speed, but will be hidden).
There are two to four forms of MOVSPR, depending on how you count... at the highest level, there are only 2 forms:
  1. Cartesian (rectangular) co-ordinates
  2. Polar (angle + magnitude) co-ordinates
However BASIC allows two (very useful) sub-forms of each, so in general you might say there are 4 forms:
  1. Cartesian (rectangular) co-ordinates -- Absolute Immediate
  2. Cartesian (rectangular) co-ordinates -- Relative Immediate
  3. Polar (angle + magnitude) co-ordinates -- Relative Immediate
  4. Polar (angle + magnitude) co-ordinates -- Relative Temporal
Actually MOVSPR is quite flexible and lets you mix forms 1 and 2 ... so REALLY (at the lowest level) there are 6 forms:
  • Absolute X, Absolute Y (rectangular/Cartesian) -- Immediate
  • Relative X, Absolute Y (rectangular/Cartesian) -- Immediate
  • Absolute X, Relative Y (rectangular/Cartesian) -- Immediate
  • Relative X, Relative Y (rectangular/Cartesian) -- Immediate
  • Relative Polar (angle + magnitude) -- Immediate
  • Relative Polar (angle + magnitude) -- Temporal
To keep things reasonably simple, we'll say there are 4 forms (but you can easily make 6).  The important thing is the first 3 discussed will (re)position a sprite immediately (one-time); these are the MOVSPR xVal, yVal (relative or absolute) and MOVSPR distance; angle forms.  The 4th (last) form sets a SPRITE's motion (the MOVSPR angle # speed form) -- its position will be continuously updated at a periodic rate (temporal update every IRQ).  

When positioning the sprite, it is important to note that coordinates are relative to high-resolution pixels; it does matter if the SPRITE is high-res or multi-color, and it does not matter if the video mode is high-res or multi-color.  Perhaps more importantly, the coordinate is adjusted when SCALE is in effect.
The xVal, yVal form of MOVSPR allows you to position a sprite using either absolute coordinates (form 1), relative coordinates (form 2), or a mixture of both (see examples).  The top-left pixel of the sprite is moved to the indicated screen coordinate.  In particular, sprite coordinates range from (24,50), the top-left corner of the visible screen, to (343,249), the bottom-right corner of the visible screen.  Coordinates outside this range will generally result in the sprite being invisible or partially clipped.  However, the X ordinate is actually set as xVal mod 512 (so values greater than 511 will "wrap around"), and the Y ordinate is set as yVal mod 256 (so values greater than 255 will "wrap around").
When using the xVal, yVal form of MOVSPR (Cartesian / rectangular), it is important to remember not to include a leading minus (-) with any ordiante (assuming you want an Absolute position).  This also applies to a leading plus (+), but that is extremely rare!  Including a literal plus (+) or minus (-) to either of these parameters will cause them to be interepereted as Relative to the current position of the sprite.  If you want to specify a negative absolute ordinate using a literal value, be sure to enclose the value in parentheses "(" and ")".
The last two (main) forms are both Relative Polar; that is, they are always Relative to the sprite's current position and they always use Polar (angle and magnitude) parameters.  However, these last two forms are quite a bit different than the first two forms.  On reason is the syntax of BASIC: for form 3 (immediate) the values are written as "magnitude ; angle" but for form 4 (temporal) the values are written "angle # magnitude".  Besides the syntax, the semantics (meaning) is also quite different: the third form is immediate (one-time only) while the fourth/last form is temporal (continuous update over time).

In both polar cases (form 3 and 4), The angle is measured in clockwise degrees, relative to 0 being "up" (towards the top of the screen).  The magnitude is measured in (high-resolution) pixels.

With the distance; angle syntax (form 3) of MOVSPR, the distance (magnitude) is always a signed value, so a negative value will actually move the sprite in the opposite direction of the specified angle.  Both angle and distance use the same units as high-resolution bitmap commands; see GRAPHIC.
The final form, MOVSPR angle # speed, will set the sprite in motion (or stop it from moving).  The speed is the number of pixels (magnitude) that the sprite will move each IRQ, which occurs 60 or 50 times per second, per machine NTSC/PAL video standard.  This means BASIC programs using MOVSPR are often not compatible between video standards, unless the programmer specifically accounts for the difference!  BASIC actually maintains a secret variable for each sprite which includes "sub-pixel" information, so a slow-moving sprite may not move a real pixel during an IRQ.  This is a good thing, as it allows for smooth animation in any direction at (almost) any speed.
Important notes about MOVSPR angle # speed include:
  • The speed is evaluated modulo 16, so values greater than 15 are not recommended.
  • This form of MOVSPR is incompatible with the polar form (MOVSPR distance; angle) which will move the sprite in the opposite direction if distance is negative but the temporal (form 4) of MOVSPR will not do so when speed is negative!
  • Although angle is used in the same manner in both the angle # speed and distance; angle forms of MOVSPR, the location of parameter angle changes. 
In case it isn't obvious, the MOVSPR angle # speed form may be used to stop the sprite from moving by specifing a speed of zero.
If any parameter is omitted or is an invalid expression, or if any extra parameter(s) are given, then SYNTAX ERROR occurs.  If any parameter is not numeric, TYPE MISMATCH ERROR occurs; you may manually convert a string with VAL.  Any floating-point parameter is automatically converted with INT.  If the result is not a Legal Value (see table above), ILLEGAL QUANTITY ERROR occurs.
Examples (sprites 1 and 8 should be enabled to see the effects) :
MOVSPR 8,343,249   : REM position sprite 8 at the bottom-right pixel [form 1]

MOVSPR 8, 24;270   : REM re-position sprite 8 by 24 pixels "left" (270 degrees) [form 3]

MOVSPR 8, -295,150 : REM position sprite 8 at relative X and absolute Y [mix form 1 + 2]

MOVSPR 8, +24,50   : REM position sprite 8 at relative X and absolute Y [mix form 1 + 2]

MOVSPR 8, (+24),50 : REM position sprite 8 at absolute X and Y (top left) [form 1]

MOVSPR 8, 45 # 5 : REM animate position to top left (45 degrees) at 5 pixels/IRQ [form 4]

  Compare With  
  Contrast With  
  See Also  

© H2Obsession, 2014, 2017