-
Notifications
You must be signed in to change notification settings - Fork 0
development beyond sample
This section assumes you have been through the demonstration.
Adjustments enable the creator to make changes to php session based variables. These variables then can be used to track state and make logical decisions on what information to present to the user.
Example
Adjustment::with('gold_key', 1);
This would make a change so the gold_key variable has a value of 1.
Conditions are basic logical operations using the values set by an adjustment.
Example
EqualCondition::with('gold_key', 1);
For this condition to pass the variable gold_key would need to have a value of 1.
The php session is used to persist adjustments. It can optionally be partitioned so you can store variables in different collections. There is a default collection for all adjustments and conditions.
Input requests are the heart of the engine. Each input request represents one screen. The user is prompted with any number of response options (including zero).
Example
InputRequest::with('Welcome to the SAMQ (Stop Asking Me Questions) sample.', null);
The text indicated would be displayed. There would be no responses for the user to select (a dead end!).
InputRequests are registered with the engine using the $samqCore->addRequest call, indicating a unique identifier to associate with the InputRequest.
Responses link the current Input Request to the next. By selecting a response the user is transitioned to the indicated destination. When a response is selected data is POST'd to the engine to indicate the transition.
Example
Response::with('Choice 1', 'destination_01');
This response would have the text Choice 1 and a destination of destination_01.
There are a number of calls that must be made for the engine to function. See the sample index.php (in the root folder).
Learn more about the PHP Session. This is not absolutely required depending on the functionality you intend to use. Anything involving conditions / adjustments requires a session.
session_start();
This includes all the files necessary for everything to function.
include_once dirname(__FILE__) . '/core/core_include.php';
This creates a new core for use throughout the rest of the code. It also specifies the initial/default InputRequest sample_01. Finally the POST path is specified. This is critical as every time the user clicks on a response the data is POST'd to the path specified. Also the $samqCore variable is global so you can easily use it in files like the sample sample_input_requests.php.
define("SAMQ_POST_PATH", "/");
$samqCore = new SAMQCore('salty!', 'sample_01', SAMQ_POST_PATH);
This is the heart of the processing to render the destination InputRequest. Get, pre-process, render, and finally post-process.
$destinationInfo = $samqCore->getDestinationInfo();
$destinationInfo->destinationRequest->preProcess();
$destinationInfo->destinationRequest->render($samqCore);
$destinationInfo->destinationRequest->postProcess();
The code above is heavily reduced from the sample index.php for clarity.
I think this is a critical item... Sometimes you just need to start over completely.
echo '<p><span class="standard"><a href='.$samqCore->getPostPath().'>Start Over</a></span></p>'.DBG_EOL;
This performs a GET with no data so the engine defaults to the InputRequest specified in the engine initialization (like when you first navigate in the browser).
There is other functionality related to request codes (think old game passwords) and jumping directly to a request by id, but those are not critical unless needed.
The sample InputRequests included in the sample_input_requests.php file are quite compact. The engine was built with this in mind to avoid the need to create excessive variables.
Example from the file:
MapUtils::getXY($sampleRequestMap, 2, 1)
->setNorthResponse(
MoveInputRequest::createMoveResponse('n', 'sample_map_02_00')
->setEnabledOnAnyConditions(EqualCondition::with(KEY_USED, 1))
->setDefaultState(ResponseState::Disabled))
->setCommandResponse(
Response::with('Unlock', 'sample_map_02_01')
->setEnabledOnAllConditions(EqualCondition::with(KEY, 1))
->setHiddenOnAnyConditions([
EqualCondition::with(KEY_USED, 1),
NotEqualCondition::with(KEY, 1)
])
->setDefaultState(ResponseState::Disabled)
->setAdjustments(Adjustment::with(KEY_USED, 1))
);
In that single mammoth call there are numerous conditions, adjustments, and a response created. The main goal was to allow the author to create and completely define an InputRequest in a single command.
// gets the location on the map at 2,1
MapUtils::getXY($sampleRequestMap, 2, 1)
// override the default north response
->setNorthResponse(
// make a new move input request
MoveInputRequest::createMoveResponse('n', 'sample_map_02_00')
// enable the response if the key has been used
->setEnabledOnAnyConditions(EqualCondition::with(KEY_USED, 1))
// default the response to being disabled
->setDefaultState(ResponseState::Disabled))
// setup a command response (the middle button)
->setCommandResponse(
// setup a basic response with the text and destination indicated
Response::with('Unlock', 'sample_map_02_01')
// Enable this response if the key is in the inventory
->setEnabledOnAllConditions(EqualCondition::with(KEY, 1))
// setup all the potential conditions to hide this response
->setHiddenOnAnyConditions([
// hide if the key is used
EqualCondition::with(KEY_USED, 1),
// hide if the key is not in the inventory (this is where order of evaluation is critical)
NotEqualCondition::with(KEY, 1)
])
// default the response to disabled
->setDefaultState(ResponseState::Disabled)
// if the response is selected change the key used state
->setAdjustments(Adjustment::with(KEY_USED, 1))
);
The best way to move forward is to mess with the sample_input_requests.php file. Make some new InputRequests. Tweak the existing. Try to add another map. As you move forward you will likely want to organize your requests across multiple files like the sample_input_requests.php file.