Contents

1. Introduction
2. System Requirements
3. Operating Environment
4. Installation
5. How to Use
6. Known Bugs
7. File List
8. Building Samples
9. Notes
10. Specifications
11. Comments and Notes About License Information

1. Introduction

This package is the expanded communication library for CTR and includes functions for peer-to-peer communication, matchmaking, and ranking.
For the revision history of this library, see document/manual/history.html.
For a summary of changes from CTR-NEX 2.7.3, see document/manual/difference_from_nex_2_x.html.

2. System Requirements

The CTR-SDK must be installed to build CTR-NEX.

3. Operating Environment

CTR-SDK

CTR-SDK 11.0.0

4. Installation

Expand this package in a directory whose name includes neither spaces nor Japanese characters.
The following environment variables must be set to build the sample demo.

• CTRSDK_ROOT
  
The directory where CTR-SDK is installed.
• CTRNEX_ROOT
  
After expanding the package, double-click SetupCTR.wsf to run setup. The executed directory is set as the environment variable CTRNEX_ROOT.

5. How to Use

Set the following path as the include path, and include nex.h.

$(CTRNEX_ROOT)\include

Link the libraries in the following path according to the build target.

$(CTRNEX_ROOT)\libraries

6. Known Bugs

For the latest information, including information about bugs identified after the release, see the Technical Information section of the Nintendo Developer Portal.

7. File List

• include
  
Contains the headers that can be included in applications.
• libraries
  
Contains the libraries that can be linked by applications.
• Sample
  
Contains samples.
• bin
  
Contains the tools needed for building.
• Documentation
  
Includes documents such as the Programming Manual and API Reference.

8. Samples

Building Samples

Run omake in $(CTRNEX_ROOT)/Sample.

You need the lib_demo library to build the sample.
To build the lib_demo library, run omake in SampleDemos/common of the sample demo package that was published together with the CTR-SDK.

String Notation in Samples

In the sample program code, wide characters strings are written by wrapping the string in the _T macro (for example, _T("foo")).

9. Notes

• Initialization and Finalization
  
You must initialize the library before using any of the library's features, and you must finalize the library when you are done.

1. Initialization Process
   
If you are using an application-specific allocator, first set the allocator by using the MemoryManager:SetBasicMemoryFunctions function.
The memory-allocation function that you specify must return a valid pointer.
Applications should handle the process as follows.

• Shut down the library if you are going to allocate more memory than was prepared.
  
• In advance, allocate an amount of memory close to the amount that was used when the library was executing before shutdown — typically between several KB to several dozen KB. If memory allocation fails during the initialization process, this previously allocated memory is released.
  (Because memory is freed, the memory-allocation process can now succeed.) Then shut down the library.
  

Next, call the GlobalVariables::AcquireInstance function to create the global variables used by the library.

2. Finalization Process
   
Call the GlobalVariables::ReleaseInstance function to free the global variables used by this library.


• Using the Duplicate Object (User DO) Feature
  
Contact Nintendo if you plan to upload a master that uses the NEX P2P duplicated object (user DO) feature.

• NetZ Initialization
  
If you use the user DO feature, register the InitDOClasses function generated by the DDL compiler by using the NetZ::SetDOClassInitializationCallback function. No special action is required if you do not use the user DO feature.

• Using HostMigrationExtension
  
You can now specify a callback to call upon migration in the constructor to HostMigrationCallback. Normally, specify the MatchMakingClient::StaticUpdateSessionHost function or the MatchmakingClient::StaticUpdateSessionHostWithOwner function.
• P2P communication compatibility with CTR-NEX 3.1, and CTR-NEX 3.2 and later
  
Fixed a bug that caused a station to be recognized only by the host when that station joined the same NetZ session two or more times with CTR-NEX 3.2 or later when nn::nex::NetZ::SetDOClassInitializationCallback was not used, such as when there were three or more units and host migration extension was not used. For this reason, there is no communication compatibility with CTR-NEX 3.1. The following revisions are recommended to connect CTR-NEX 3.1 to CTR-NEX 3.2 or later.

void InitDOClassesFix() {
    nn::nex::DOCoreDDLDeclarations::Register();
    nn::nex::OnlineCoreDDLDeclarations::Register();
}

// Before constructing NetZ.
nn::nex::NetZ::SetDOClassInitializationCallback(&InitDOClassesFix);

In some cases, such as when the master is already up, you must use the following code after CTR-NEX 3.2 to communicate with unrevised CTR-NEX 3.1.

#include <NetZ/src/Core/SessionClock/SessionClockExtension.h>

void InitDOClasses() {
    nn::nex::SessionClockExtDDLDeclarations::Register();
    nn::nex::DOCoreDDLDeclarations::Register();
}

// Before constructing NetZ, you need the following:
nn::nex::NetZ::SetDOClassInitializationCallback(&InitDOClasses);

However, the problem cannot be fixed with this implementation.
• When Using a Server
  
You must specify a game server ID and access key to access a server that provides features for matchmaking and ranking.
In the sample contained in this package, a game server ID and an access key are specified for the sample.
All developers using this library share the same server region that is accessed using the game server ID and access key for this sample.
If you need a dedicated server region, please contact Nintendo at support@noa.com.
• Build Types and Link Libraries
When linking NEX libraries, link the NEX library with the same build type (noopt, verbose, release) as the build type (debug, development, or release) of the application using NEX.
Applications may not run normally if the same build type is not used.
• Flag Definitions for Include
Be sure that the flags used when including header files for this library conform to flag settings for the build system included with the CTR-SDK.
Specifically, for release builds, you must not define NN_BUILD_VERBOSE, NN_BUILD_DEVELOPMENT, NN_BUILD_DEBUG, or NN_BUILD_NOOPT.
For development builds, you must not define NN_BUILD_RELEASE, NN_BUILD_DEBUG, or NN_BUILD_NOOPT.
For debug builds, you must not define NN_BUILD_RELEASE or NN_BUILD_DEVELOPMENT.
For more information about flag definitions for each build, see the CTR-SDK build system.
Applications may not run normally if built using flag settings that differ from the build system included in the CTR-SDK.
• Updating the Game Server
The library checks the server version when a user logs in, and if the server version is earlier than the one required by the library, it is not possible to log in to the game server. Accordingly, if the NEX library used by the application is updated, the game server also must be updated. Make the game server update request from OMAS. (Game servers do not update automatically.)

• Distribution of Small Build
This package only includes the fast build of the library. Contact Nintendo if you need the small build of the library.

10. Specifications

• Static initializer sometimes calls new.
  
The CTR-NEX library uses qVector<T>::reserve in several locations.
The qVector<T>::reserve template inherits from the std::vector<T>::reserve template, which itself calls _RW::__rw_throw, such that the static initializer calls new.
This allocates 8 bytes of memory from the global heap, and this allocation cannot be increased.

11. Comments and Notes About License Information

This library includes software developed by Quazal Technologies Inc.
However, direct all requests for support and queries concerning this library to Nintendo.

CONFIDENTIAL