There is a powerful MEMS accelerometer in the very center of your Circuit Playground. This part is the LIS3DH, a 3-axis (X, Y and Z) sensing accelerometer. Accelerometers are the sensors in your WiiMote, phone, and other electronic devices that can sense tilt, gravity, motion and 'tap' effects. These sensors used to cost $20 each but now are so common we can include them for beginners!
The sensor can sense ±2g, 4g, 8g (g = 9.8 meters/s2). Of course, at all times on earth you will sense 1 g of gravity!
The LIS3DH is connected to the hardware SPI pins (to leave the I2C pins free) and has the chip select (CS) pin on digital pin #8 and an optional interrupt output on digital pin #7 (also known as IRQ #4)
Motion in X Y and Z
You can ask the sensor for the amount of g detected in X, Y and Z directions. Positive values mean acceleration in the direction of the arrow on the silkscreen. For X that means towards the USB jack. For Y that is to the left. For Z that is straight up pointing towards you when looking at the circuit board.
CircuitPlayground.motionZ() will each return a floating point value.
Setting Accelerometer Range
You can change the range, a smaller range (±2g) will give more precision. Larger ranges (±8g) can sense greater forces. You can set it whenever you like using
CircuitPlayground.setAccelRange(range) where range can be
You can turn on tap detection by calling
Tap detection can detect single taps or 'double taps' (like a double-click). If taps is 1 you will only detect single taps, one at a time. If taps is 2, you will be able to detect both single taps and double taps.
You can detect taps in real time by calling
CircuitPlayground.getAccelTap(). It will return 0 if no tap is detected, 1 if a single tap is detected, and 2 or 3 if double tap is detected.
The problem with that is you need to query it within about 100 milliseconds of the tapping, which can be difficult to do. If you are comfortable with interrupts you can use the interrupt output to have a function called when a tap is detected:
attachInterrupt(digitalPinToInterrupt(7), myfunction, RISING) will call myfunction whenever the tap or doubletap occurs.