development move input requests

SAMQ Development: Move Input Requests

MoveInputRequest is a special type of InputRequest that provides orthogonal prompt options for moving north, east, south, and west. Each direction option is Response object and can be configured accordingly.

Additional Functionality

Command Response

The command response is an option that appears in the middle of the direction buttons.

Additional Response

Any additional responses are shown below the direction buttons.

Map Generation

MapUtils is a class with a collection of static utility methods to help with the creation of maps of MoveInputRequests.

The map utilities always operate on an X x Y grid (0,0 is the top left and X,Y is the bottom right). The grid should not be disjointed. It should always be rectangular. This is just how it is (not impossible to support non-rectangular...).

Here are the basic steps to creating a map:

Create Defines (highly recommended!)

If you are writing Php with a monospaced font (let's hope so) creating a map will be much easier if you keep each location in the map the same character width. This will make more sense in the layout array in the next step.

define("REGION", "");
define("______", null);

Use of these defines is not absolute. I just recommend you make 6 character length defines for use when creating the layout grid described below.

REGION (define)

This define indicates a location for the map utility to treat as player accessible. All directions from a REGION will be checked and the allowed exits will be automatically generated.

______ (define)

This define is used to indicate an area the player should never access.

Create the Layout Grid

This grid defines the rules about the map.

$sampleMapLayout = array(
    //    0       1       2       3       4
    array(______, ______, REGION, "xxxw", "xxsx"),//0
    array(______, ______, REGION, ______, REGION),//1
    array(______, REGION, REGION, REGION, REGION),//2
    array(______, ______, REGION, ______, REGION),//3
    array(______, ______, REGION, ______, REGION),//4
);

The REGION and ______ items are described above. The quoted text that looks like xxxw and xxsx is something entirely different.

Overriding Auto-Generation

When the map is generated anything null will be considered inaccessible and anything non-null is considered accessible. All directions from an accessible location will be checked to see if a link should be automatically created. This may incorrectly link two or more locations together that you do not want connected. The characters n e s w each signify a valid exit to check. If you accidently specify one that does not lead to another accessible location it will be ignored. If a given direction is not in the string that direction will not be accessible. For example, the two entries in the top right will not link to one another because the left item does not have e in the string and the right item does not have w in the string. The x character is just used as a character to fill the spacing out to 6 characters.

Note: Code Confusion

This is just a note for anyone paying close attention to how the array is laid out for the map. Accessing an item in the map would require specifying the y then the x value: $sampleMapLayout[$y][$x] The opposite would be a confusing mess. To work around this issue you should use the MapUtils::getXY method to perform the lookup.

Generate the Id map

$sampleMapIds = MapUtils::generateIdMap($sampleMapLayout, 'sample_map_');

This process generates the ids for the map layout by combining the prefix specified with the position information. Example: sample_map_02_04 is an id automatically generated representing postion 2,4.

Generate the Request map

$sampleRequestMap = MapUtils::buildMap($sampleMapIds, $sampleMapLayout);

This creates the map of requests by combining the layout and id maps.

Tweak the MoveInputRequests

Before registering the map with the engine you should change anything within the map that needs to be adjusted.

MapUtils::getXY($sampleRequestMap, 4, 4)
    ->setCommandResponse(
        Response::with('Pick up key', 'sample_map_04_04')
            ->setHiddenOnAnyConditions([
                EqualCondition::with(KEY, 1),
                EqualCondition::with(KEY_USED, 1)
            ])
            ->setAdjustments(Adjustment::with(KEY, 1))
    );

The above customization places a key in a location and offers the ability (command response) to pick it up.

MapUtils::getXY($sampleRequestMap, 2, 2)
    ->setNorthResponse(
        MoveInputRequest::createMoveResponse('n', 'sample_map_02_01')
            ->setEnabledOnAnyConditions(EqualCondition::with(KEY_USED, 1))
            ->setDefaultState(ResponseState::Disabled));

The above customization adjusts the north movement to use a new request with some custom state handling. See the method descriptions in the code for more details.

Register the map

Finally after all the adjustments you need to register all of the MoveInputRequests with the engine. MapUtils::addRequests helps with this.

MapUtils::addRequests($samqCore, $sampleMapIds, $sampleRequestMap);