UWP Alien Sokoban - Part 3

Introduction

This is part 3 of a 3 part series in which you explore how to implement a XAML based game for the Universal Windows Platform (UWP).

Links to articles in this series:

• Part 1
• Part 2
• Part 3 (this article)

Retrieving a Map

public async Task<string> GetMapAsync(int levelNumber)
{
 string fileUrl = string.Format(@"ms-appx:///{0}Level{1:000}.skbn",
    levelDirectory, levelNumber);
 
 StorageFile file = await StorageFile.GetFileFromApplicationUriAsync(new Uri(fileUrl));
 string levelText = await FileIO.ReadTextAsync(file);
 
 return levelText;
}

Exploring the Cell Control

void UpdateDisplay()
{
    wallImage.SetVisibility(cell is WallCell);
    floorImage.SetVisibility(cell is FloorCell || cell is GoalCell);
    floorHighlightImage.SetVisibility(hasMouse && (cell is FloorCell || cell is GoalCell));
    treasureImage.SetVisibility(cell.CellContents is Treasure);
    playerImage.SetVisibility(cell.CellContents is Actor);
    goalImage.SetVisibility(cell is GoalCell && !(cell.CellContents is Treasure));
    goalActiveImage.SetVisibility(cell is GoalCell && cell.CellContents is Treasure);
}

The SetVisibilitymethod is a custom extension method that alleviates the need for a ternary expression to set Visibility property of the UIElement. It reduces verbosity. See Listing 3.

Listing 3. UIElementExtensions SetVisibility method.

public static void SetVisibility(this UIElement element, bool visible)
{
    element.Visibility = visible ? Visibility.Visible : Visibility.Collapsed;
}

In other words, it turns this:

wallImage.Visibility = cell is WallCell ? Visibility.Visible : Visibility.Collapsed;

Into this:

wallImage.SetVisibility(cell is WallCell);

As an aside, it’s a pity Microsoft didn’t take the opportunity to replace the UIElement’s Visibility property with a simpler boolean property, since many less important things have been overhauled in UWP. Surely, it’s a bit late to introduce a new visibility enum value (such as Android’s ‘Gone’ visibility value).

Moreover, there is no built-in BooleanToVisibilityConverter in the SDK, which means that new developers predominately get stuck figuring out how to hide or reveal an element based on a boolean value. The good news is that with the Windows 10 Anniversary Update, x:Bind now implicitly converts to and from a bool and a Visibility enum value. This will, however, only work on machines and devices running the Anniversary update.

Bitmap Caching

Bitmaps can take up large amounts of memory. If you intend your UWP app to run on a phone then you need to be mindful of keeping your memory usage to a minimum.

NOTE: On Windows Mobile, for devices with over 1GB of RAM, your app can use no more than 390 MB. This limit is imposed regardless of how much system memory is available, and if you exceed it, the OS will exit your app.

To reduce the amount of RAM that the Sokoban game needs, BitmapImage objects are cached in a dictionary. While each cell has its own set of Image objects, it shares the underlying BitmapImages with other CellControls.

The image cache is a simple static Dictionary in the CellControl itself, as shown:

static readonly Dictionary<string, BitmapImage> imageCache
   = new Dictionary<string, BitmapImage>();

When a CellControl is instantiated, a set of Image objects are also created. See Listing 4. The CreateContentImage method first attempts to retrieve an image using the relativeUrl parameter. If an Image has previously been created, it is assigned to the Source property of the Image.

Listing 4. CellControl CreateContentImage method

Image CreateContentImage(string relativeUrl)
{
  Image image = new Image
  {
   HorizontalAlignment = HorizontalAlignment.Stretch,
   VerticalAlignment = VerticalAlignment.Stretch,
   Stretch = Stretch.Fill
  };

 BitmapImage sourceImage;

 if (!imageCache.TryGetValue(relativeUrl, out sourceImage))
 {
  Uri imageUri = new Uri(BaseUri, relativeUrl);
  sourceImage = new BitmapImage(imageUri);
  imageCache[relativeUrl] = sourceImage;
 }

 image.Source = sourceImage;

 return image;
}

Responding to Touch Events

Implementing Thread-Safe Async Await with Semaphores

lock (aLock)
{
    await DoSomethingAsync();
}

async Task<bool> JumpAsync(Jump jump)
{
 bool result = false;
 
 try
 {
  await moveSemaphore.WaitAsync();
 
  SearchPathFinder searchPathFinder = new SearchPathFinder(Cell, jump.Destination);
  if (searchPathFinder.TryFindPath())
  {
   for (int i = 0; i < searchPathFinder.Route.Length; i++)
   {
    Move move = searchPathFinder.Route[i];
 
    /* Sleep for the stepDelayMS period. */
    await Task.Delay(stepDelayMS).ConfigureAwait(false);
 
    Location moveLocation = Location.GetAdjacentLocation(move.Direction);
    Cell toCell = Level[moveLocation];
 
    if (!toCell.TrySetContents(this))
    {
     throw new SokobanException("Unable to follow route.");
    }
    MoveCount++;
   }
   /* Set the undo item. */
   Jump newMove = new Jump(searchPathFinder.Route) { Undo = true };
   moves.Push(newMove);
   result = true;
  }
 }
 finally
 {
  moveSemaphore.Release();
 }
 
 return result;
}

internal bool DoMove(Move move)
{
 try
 {
  moveSemaphore.Wait();
 
  return DoMoveAux(move);
 }
 finally
 {
  moveSemaphore.Release();
 }
}

A Note About Image Assets

Implementing a Slide-In Menu

• Undo Move
• Redo Move
• Restart Level

public class DelegateCommand : ICommand
{
 readonly Action<object> executeAction;
 readonly Func<object, bool> canExecuteAction;
 
 public DelegateCommand(Action<object> executeAction,
  Func<object, bool> canExecuteAction = null)
 {
  this.executeAction = executeAction;
  this.canExecuteAction = canExecuteAction;
 }
 
 public bool CanExecute(object parameter)
 {
  return canExecuteAction?.Invoke(parameter) ?? true;
 }
 
 public void Execute(object parameter)
 {
  executeAction?.Invoke(parameter);
 }
 
 public event EventHandler CanExecuteChanged;
 
 protected virtual void OnCanExecuteChanged()
 {
  CanExecuteChanged?.Invoke(this, EventArgs.Empty);
 }
 
 public void RaiseExecuteChanged()
 {
  OnCanExecuteChanged();
 }
}

ICommands are useful because they share affinity with many UI elements, such as Buttons, which automatically leverage the CanExecute method to automatically change the IsEnabled state of the button.

public Game(IInfrastructure infrastructure)
{
 this.infrastructure = ArgumentValidator.AssertNotNull(infrastructure, nameof(infrastructure));
 LevelContentBase.SynchronizationContext = infrastructure.SynchronizationContext;
 
 RestartLevelCommand = new DelegateCommand(_ => RestartLevel());
 UndoCommand = new DelegateCommand(_ => commandManager.Undo());
 RedoCommand = new DelegateCommand(_ => commandManager.Redo());
 
 /* Reset the level number to 0 if a debugger is attached. */
 if (Debugger.IsAttached)
 {
  infrastructure.SaveSetting(levelKey, 0);
 }
}

Materializing the Commands

<SplitView Grid.Row="1" x:Name="splitView"
   DisplayMode="Overlay"
   OpenPaneLength="320"
   PaneBackground="{ThemeResource ApplicationPageBackgroundThemeBrush}"
   IsTabStop="False" VerticalAlignment="Stretch" VerticalContentAlignment="Stretch">
 <SplitView.Pane>
  <StackPanel Background="{ThemeResource ChromeSecondaryBrush}">
   <Button Command="{x:Bind Game.RestartLevelCommand}"
      Content="Restart Level"
      Click="HandleMenuButtonClick"
      Style="{ThemeResource MenuItemTextButtonStyle}"/>
    <Button Command="{x:Bind Game.UndoCommand}"
      Content="Undo"
      Click="HandleMenuButtonClick"
      Style="{ThemeResource MenuItemTextButtonStyle}"/>
    <Button Command="{x:Bind Game.RedoCommand}"
      Content="Redo"
      Click="HandleMenuButtonClick"
      Style="{ThemeResource MenuItemTextButtonStyle}"/>
  </StackPanel>
 </SplitView.Pane>
 <SplitView.Content>
  <Grid x:Name="gameCanvasContainer" VerticalAlignment="Stretch" 
        HorizontalAlignment="Stretch" Background="Transparent">
   <Canvas x:Name="gameCanvas" Background="Transparent" />
  </Grid>
 </SplitView.Content>
</SplitView>

void HandleMenuButtonClick(object sender, RoutedEventArgs e)
{
 splitView.IsPaneOpen = false;
}

<ToggleButton
 FontFamily="Segoe MDL2 Assets"
 Content="&#xE700;"
 Foreground="White"
 Background="Transparent"
 BorderBrush="Transparent"
 TabIndex="1"
 AutomationProperties.Name="Navigation"
 ToolTipService.ToolTip="Navigation"
 IsChecked="{Binding IsPaneOpen, ElementName=splitView, Mode=TwoWay}" />

History

October 26 2016

• First published