CCR BallPaths

This tech tip covers the Cosmic Cart Racing BallPaths and the module driver API.

Physical Features

There are 7 rings on the module: 3 rings on the left ramp and 4 rings on the right ramp.

        lRampFrontRing

        lRampEnterRing

        lRampExitRing

        rRampRightRing

        rRampCenterRing

        rRampLeftRing

        rRampExitRing

The rings are decorative, except that lRampEnterRing, lRampExitRing, and rRampExitRing each contain a vertical opto switch.

Note that the left-ramp front ring is located at the start of the left ramp, but it is not considered the ramp entrance because it has no switch.

There are 4 magnets, all located in the mid backpanel: 3 magnets aligned with the right ramp rings in the back and 1 aligned with the VUK feeding lane.

RightRampRingLeft

RightRampRingCenter

RightRampRingRight

outerLoopMagnet

The right ramp magnets are actively cooled with computer fans. The outerLoopMagnet is not actively cooled.

Every magnet has 3 opto switches (Left, Center, Right). The Left and Right switches for the right ramp magnets are 3.5 cm away on either side. The Left and Right switches for the outerLoopMagnet are in the module top corners, far from the magnet.

There is an up post in the inner loop that can block the ball path and force the ball to drop in the inner loop hole.

Similarly, there is an up post in the outer loop that can block the ball path and force the ball to drop in the outer loop hole. That up post also serves as the VUK feeding the right ramp through the backpanel.

The module prototype included a third up post, but it was omitted from the production version.

There are 4 stand-up targets (target0 to target3) plus the captiveBall target at the end of the captive ball trough. There is no switch for the captive ball bash tube.

List of switches

The application should not handle these switches. The application should use BallPaths and the module driver API instead.

PlayfieldModuleSettings

The CCR module driver declares these PlayfieldModuleSettings:

BallPaths

There is no need to establish BallPaths on CCR because all BallPaths are static. Dynamic BallPaths were invented later and never backported to this module. The magnets and up posts are controlled with an API instead. See the sections below for details.

This table lists all BallPaths with their Started and Completed events.

A * in the first column indicates the BallPath behaves in an unexpected way.

The driver can distinguish between an inner or outer loop shot from left-to-right or right-to-left, but the switch that completes the BallPath also starts the BallPath in the opposite direction. The BallPath in the opposite direction never completes and times out. Unfortunately, that means StartedEvents for inner and outer loops are unsuitable to give an early audio or visual cue that the shot is in progress. For these shots, it’s better to give feedback only with the CompletedEvent. The RightLoop is not affected by this since it is unidirectional.

For loop and ramp shots (OuterLoopLeft, InnerLoopLeft, LeftRamp, InnerLoopRight, RightLoop, RightRamp, OuterLoopRight), the event argument for the StartedEvent is the EntranceName as a string. The event argument of the CompletedEvent is the ExitName as a string. The application typically ignores the event argument for these events. For these shots only, the driver also posts the ModeToModes event Evt_ShotMade just before the CompletedEvent (event argument is the BallPath name as a string).

The Boolean setting “Award right loop w/ target” determines whether target3 awards a RightLoop shot when hit. If not using target3, the RightLoop is completed when the rightLoop switch is activated. In both cases, the StartedEvent is sent immediately before the CompletedEvent in response to the switch activation. This means the RightLoop BallPath StartedEvent is unsuitable to give an early audio or visual cue.

InnerLoopHole is a unidirectional hole entry through VUK 2. ScoopHole is the hole entry corresponding to the bidirectional TroughLauncher through VUK 3 named LeftVUK. OuterLoopHole is the hole entry corresponding to the bidirectional TroughLauncher through VUK 6 named RightVUK. Interestingly, Lexy Lightspeed also had exactly 2 TroughLaunchers named LeftVUK and RightVUK.

CCR has a TroughLauncher with custom code on VUK 6 named RightVUKToLeftInlane. The module definition file uses VUK 14 which is VUK 6 + 8. Adding a multiple of 8 is what indicates this TroughLauncher shares the same VUK with another TroughLauncher.

TroughLauncher LeftVUK Destination is wrong in CCR.json version 2.4.0.0. It says LowerPlayfield when it should be UpperPlayfield.

The StartedEvents for Hole BallPaths are wrong in CCR.json version 2.4.0.0. The driver sends the same ModeToModes event for all 3 Hole BallPaths: Evt_BallEnteredHole. The event argument is the VUK number as an int.

The SDK spec says a driver that implements a Hole BallPath on a bidirectional TroughLauncher must block the Evt_TroughLauncherEntry event from reaching the application. The CCR module driver mode that implements this runs at priority 170. Make sure the mode in your application that handles Hole BallPaths and Evt_TroughLauncherEntry is at a lower priority. In P3SampleApp, that mode is HomeMode and it runs at priority 20.

Target BallPaths are pure switch events. The driver does not post ModeToModes events for Target BallPaths. This is allowed by the BallPath spec.

This table lists the events posted by the module driver when a particular BallPath is completed. An event in bold indicates an unusual event.

Up Post API

Raising an up post will block the ball path within the loop. The inner loop up post consistently diverts the ball into the inner loop hole. The outer loop up post typically sends the ball back where it came from; only slow balls are diverted into the outer loop hole.

To enable the up post for a specific shot:

        PostModeEventToModes("Evt_EnableBlock", "InnerLoopLeft");

        PostModeEventToModes("Evt_EnableBlock", "InnerLoopRight");

        PostModeEventToModes("Evt_EnableBlock", "OuterLoopLeft");

        PostModeEventToModes("Evt_EnableBlock", "OuterLoopRight");

The up post stays down but raises briefly as soon as the entrance switch is detected for the shot.

The outer-loop up post is temporarily disabled while the outerLoopMagnet is holding a ball. The up post will be re-enabled automatically when the magnet no longer holds the ball.

To disable the up post for a specific shot:

        PostModeEventToModes("Evt_DisableBlock", "InnerLoopLeft");

        PostModeEventToModes("Evt_DisableBlock", "InnerLoopRight");

        PostModeEventToModes("Evt_DisableBlock", "OuterLoopLeft");

        PostModeEventToModes("Evt_DisableBlock", "OuterLoopRight");

API Reference

CCR’s UsageInstructions.txt does an excellent job of explaining the ring magnet API.

This section summarizes the CCR module driver API. Events not documented in UsageInstructions.txt are shown in bold.

Magnet Names

The magnet name is sent and received as a string.

The outerLoopMagnet is designed to stabilize the ball during a RightVUKToLeftInlane launch. It is not designed to catch a ball flying around the loop. This explains why there is no API for it.

Shot Names

The shot name is sent and received as a string.

Request events

        Usage: PostModeEventToModes(eventName, evtData);

Status events

        Usage: AddModeEventHandler(eventName, handler, Priority);

Blocking with the up post is temporarily disabled in the outer loop when the outerLoopMagnet holds a caught ball during a RightVUKToLeftInlane launch.

Remember to disable magnets when the mode is stopped because that is not done automatically.