You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/contributing.md
+22-24Lines changed: 22 additions & 24 deletions
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,11 @@
1
1
---
2
-
title: Contributing Guidelines
2
+
title: Contributing to MonoGame Documentation
3
3
description: Instructions on how to contribute to the documentation of the MonoGame Framework
4
4
---
5
5
6
-
# Contributing to MonoGame Documentation
7
-
8
6
Thank you for choosing to contribute to the MonoGame project! This page provides guidance on how you can help to improve the documentation for MonoGame.
9
7
10
-
# Getting Started
8
+
##Getting Started
11
9
12
10
> [!NOTE]
13
11
> If you are new to making contributions to open source projects, it is recommended to understand the following concepts before submitting your contribution:
@@ -17,15 +15,15 @@ Thank you for choosing to contribute to the MonoGame project! This page provides
17
15
> -[Creating a new file](https://help.github.com/articles/creating-new-files/) or [editing an existing one](https://help.github.com/articles/editing-files-in-your-repository/) using the GitHub markup editor.
18
16
> -[How to submit your contributions for review through a pull request](https://help.github.com/articles/creating-a-pull-request/).
19
17
20
-
## Articles and API References
18
+
###Articles and API References
21
19
22
20
The MonoGame documentation contains two types of documents: articles and API references.
23
21
24
22
Articles include manuals, guides and tutorials on how to use the MonoGame Framework to create games.
25
23
26
24
API references provide detailed explanation of each class and method found in the MonoGame Framework. The documentation is written in the [C# XML format](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments) and is inline to the MonoGame source code.
27
25
28
-
## Generating the Documentation Site
26
+
###Generating the Documentation Site
29
27
30
28
The pages for articles and API references are hosted on a documentation site that is generated using [DocFX](https://dotnet.github.io/docfx/).
31
29
@@ -40,7 +38,7 @@ To generate a local copy of the documentation site:
40
38
> [!TIP]
41
39
> Verify your changes in your local documentation site before submitting a pull request with said changes. It is recommended to include screenshots of the pages in the pull request to help reviewers confirm these changes.
42
40
43
-
# General Rules
41
+
##General Rules
44
42
45
43
The following rules **must** be observed at all times when contributing documentation to the MonoGame project.
46
44
@@ -52,65 +50,65 @@ The following rules **must** be observed at all times when contributing document
52
50
> [!WARNING]
53
51
> Breaking these rules can result in your contribution being rejected.
54
52
55
-
# General Style Guide
53
+
##General Style Guide
56
54
57
55
Because there are many contributors to the MonoGame documentation, it can be difficult to maintain a coherent writing style throughout the documentation site. In addition to the [General Rules](#general-rules), this style guide serves to inform contributors of the conventions needed to maintain this writing style. So please review the following expectations before contributing any documentation.
58
56
59
-
## Every Word Should Contain Value
57
+
###Every Word Should Contain Value
60
58
61
59
Every word in the reference documentation should provide information beyond the API itself. Documentation that only rehashes or rephrases what is already apparent in the class, method, parameter, or property name has zero value and wastes time for both the writer and reader.
62
60
63
-
## The First Sentence Is the Most Important
61
+
###The First Sentence Is the Most Important
64
62
65
63
There is no guarantee that the reader will read beyond the first sentence of the reference documentation. This is why that first sentence is the most important and should convey the most key piece of information. Take your time to write the most concise and clear first sentence possible. This helps users tremendously and goes a long way towards having great documentation.
66
64
67
-
## Surface Information Hidden in the Code
65
+
###Surface Information Hidden in the Code
68
66
69
67
Being inline with the code allows you to easily look for critical information within it that the user might not know from looking at the API alone. Take your time to explore inner method calls and platform specific sections of the code. The time to write the documentation is once you feel you fully understand the code you are documenting. If you don't feel you understand the code then leave the documentation for someone else to write.
70
68
71
-
## Focus on What Adds Value to the Consumer
69
+
###Focus on What Adds Value to the Consumer
72
70
73
71
Limit documentation to public methods and functions unless there is a specific reason to include internal methods, while documenting internals helps with readability of the code, it provides limited use to consumers of the MonoGame Framework.
74
72
75
-
## Documentation Is Referenced Not Read
73
+
###Documentation Is Referenced Not Read
76
74
77
75
Remember that the user is searching for an answer for a specific question. It is your job to predict these questions and provide them clear answers.
78
76
79
-
## Descriptions Should Add Value and Understanding
77
+
###Descriptions Should Add Value and Understanding
80
78
81
79
Describing a thing by naming the thing does not help the developer to understand what the concept is that you are describing, for example:
82
80
83
81
> "The Genre class provides information about a genre"
84
82
85
83
Which does not help someone reading the documentation if they do not know what a `Genre` is. Be descriptive and improve the readers understanding for what something is and WHY it is.
86
84
87
-
# API Reference Style Guide
85
+
##API Reference Style Guide
88
86
89
87
In addition to the [General Style Guide](#general-style-guide), please consider the following conventions used for code associated with the API reference docs.
90
88
91
-
## XML Tag Guidance
89
+
###XML Tag Guidance
92
90
93
91
By default, the standard [Microsoft recommendations](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/recommended-tags) should be used for filling in XML tags for each class, method and property.
94
92
95
93
With a few points to call out:
96
94
97
-
### `<see>` and `<cref/>` should be used whenever an API reference is used in the documentation
95
+
####`<see>` and `<cref/>` should be used whenever an API reference is used in the documentation
98
96
99
97
To ensure that API documentation is linked to whichever reference is used, `<see>` and `<cref/>` references should be used, this helps users navigate the methods, especially when looking up initializers or use of a property or method.
100
98
101
-
### Avoid self referencing `<cref/>` unless it provides value
99
+
####Avoid self referencing `<cref/>` unless it provides value
102
100
103
101
`<cref/>` blocks are there to add links and create references to other classes, functions and methods that help inform the developer for what those concepts are. Adding a `<cref/>` for the same class or property you are describing just creates a circular reference that does not add value.
104
102
105
103
References to other methods or properties in the same class is fine, just avoid self if possible.
106
104
107
-
### Use descriptors in `<see/>` and `<cref/>` statements for better readability
105
+
####Use descriptors in `<see/>` and `<cref/>` statements for better readability
108
106
109
107
By default, a `<cref/>` or `<see/>` reference will use only the type you are referencing when rendered to the user, e.g. `<cref="Album.Genre"/>` will render as `Genre`.
110
108
111
109
Instead, use the descriptor in the style to render what you actually mean, for example: `<cref="Album.Genre">Album.Genre</cref>` which will always render as `Album.Genre` which is much clearer, it is the same for `<see/>` tags.
112
110
113
-
### 120 width comments for easy reading
111
+
####120 width comments for easy reading
114
112
115
113
Comments should be limited to **120** width, with overflow moving to the next line to make reading easier, for example:
116
114
@@ -125,7 +123,7 @@ and the y component uses 6 bits.
125
123
> If the `cref` description would cause the line to exceed the 120 recommendation, this is generally ok, so long as the rendered line does not exceed the limit.
126
124
> THe limit however, is more of a guideline than a hard rule, so common sense should be applied to keep the limit near 120 characters.
127
125
128
-
### Use the packed multi-line style with surrounding tags
126
+
####Use the packed multi-line style with surrounding tags
129
127
130
128
To keep the documentation packed and readable, each parameter should be contained to a single line, for example:
131
129
@@ -138,7 +136,7 @@ Creates a new instance of Bgr565.
138
136
<paramname="z">Thezcomponent</param>
139
137
```
140
138
141
-
## Interface Documentation
139
+
### Interface Documentation
142
140
143
141
Ifdocumentationisalreadyprovidedbyaninterfaceorinheritedclass, thenthe `<inheritdoc/>` tagshouldbeused. Critically, **DONOT**duplicatedocumentationasitincreasesmaintenancelater, for example:
144
142
@@ -152,7 +150,7 @@ public void Dispose()
152
150
153
151
This applies to all derived elements within a class, property or method.
154
152
155
-
## Inherited Properties
153
+
###Inherited Properties
156
154
157
155
Where a property or type is already documented in an `enum` or `static`, to avoid duplication the `<inheritdoc cref=""/>` style should be used, for example:
158
156
@@ -175,7 +173,7 @@ Where a property or type is already documented in an `enum` or `static`, to avoi
Copy file name to clipboardExpand all lines: articles/getting_started/1_setting_up_your_os_for_development_macos.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,7 @@ If you intend to also work with platforms such as `Android` or `iOS`, you will n
34
34
> [!NOTE]
35
35
> You can use `dotnet workload search` to detect any other available workloads you wish to use.
36
36
37
-
# Apple Silicon Known Issues
37
+
##Apple Silicon Known Issues
38
38
39
39
For the time being, MonoGame requires that you install the x64 version of the .NET runtime if you are running on an Apple Silicon mac in order to be able to build content. It is also required that [Rosetta](https://support.apple.com/en-us/HT211861) is enabled.
Copy file name to clipboardExpand all lines: articles/getting_started/2_choosing_your_ide_rider.md
+18Lines changed: 18 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -26,6 +26,11 @@ You can download and install Rider from: [https://www.jetbrains.com/rider/downlo
26
26
dotnet new install MonoGame.Templates.CSharp
27
27
```
28
28
29
+
> [!TIP]
30
+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments.
31
+
>
32
+
>* [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
33
+
29
34
## Creating a new MonoGame project
30
35
31
36
To get you started with Rider, here are the steps for setting up a new Rider MonoGame project.
@@ -42,6 +47,19 @@ To get you started with Rider, here are the steps for setting up a new Rider Mon
42
47
4. Press "Create"
43
48
5. You can now press `F5` to compile and debug your game, happy coding :)
44
49
50
+
## Update Project Tool references
51
+
52
+
The MonoGame Content Editor (MGCB) it a tool delivered through NuGet foryour project using the tools configuration heldin your `dotnet-tools.json` file (located in the `.config` folder of your project).
53
+
54
+
Once you have created your project you should run the following terminal/command-line command to ensure the tool (and the pipeline) is setup and readfor your project:
55
+
56
+
```dotnetcli
57
+
dotnet tool restore
58
+
```
59
+
60
+
> [!NOTE]
61
+
> If you ever change the version of the tools or want to upgrade them by editing the `dotnet-tools.json` configuration, you MUST run this command again to update the tools.
62
+
45
63
## Next Steps
46
64
47
65
Next, get to know MonoGame's code structure and project layout:
Copy file name to clipboardExpand all lines: articles/getting_started/2_choosing_your_ide_vscode.md
+18Lines changed: 18 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -49,6 +49,11 @@ By the end, you will be fully equipped to start creating games with MonoGame usi
49
49
dotnet new install MonoGame.Templates.CSharp
50
50
```
51
51
52
+
> [!TIP]
53
+
> Alternatively, consider using the Preview Packages provided by MonoGame to get access to the latest developments.
54
+
>
55
+
> - [How to install MonoGame Preview packages](../getting_to_know/howto/HowTo_Install_Preview_Release.md)
56
+
52
57
## Install Visual Studio Code C# Extensions
53
58
54
59
To transform Visual Studio Code from a simple text editor into a powerful development environment for C# projects, you must install the Visual Studio Code C# extension. This extension enhances the editor by providing syntax highlighting, code analysis, IntelliSense, and other features that significantly improve the development experience and productivity when working with C#.
@@ -89,6 +94,19 @@ You can find this extension by following the steps above and searching for "Mono
89
94
4. Once the files are created, open up the `Game1.cs` file and wait a second for the C# extension to load
90
95
5. You can now press F5, selectC# and then your projects name if Visual Studio Code asks you, and it should start up your brand new game!
91
96
97
+
## Update Project Tool references
98
+
99
+
The MonoGame Content Editor (MGCB) it a tool delivered through NuGet foryour project using the tools configuration heldin your `dotnet-tools.json` file (located in the `.config` folder of your project).
100
+
101
+
Once you have created your project you should run the following terminal/command-line command to ensure the tool (and the pipeline) is setup and readfor your project:
102
+
103
+
```dotnetcli
104
+
dotnet tool restore
105
+
```
106
+
107
+
> [!NOTE]
108
+
> If you ever change the version of the tools or want to upgrade them by editing the `dotnet-tools.json` configuration, you MUST run this command again to update te tools.
109
+
92
110
## Next Steps
93
111
94
112
Next, get to know MonoGame's code structure and project layout:
Copy file name to clipboardExpand all lines: articles/getting_started/content_pipeline/adding_ttf_fonts.md
+1-3Lines changed: 1 addition & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,6 @@ title: Adding TTF Fonts
3
3
description: Learn how to use TrueType fonts in MonoGame.
4
4
---
5
5
6
-
# TrueType fonts
7
-
8
6
MonoGame supports more than one method of using fonts, the following is an explanation of how to use TrueType fonts.
9
7
10
8
## Using TrueType Fonts with MonoGame
@@ -14,7 +12,7 @@ To be able to use a TrueType font, MonoGame requires the **TrueType font file**
14
12
> TrueType fonts may be installed on the system, or added manually in to the same directory as the .spritefont file.
15
13
16
14
1. Create the .spritefont file by selecting "Edit -> Add -> New Item" from the MGCB Editor menu, then select **SpriteFont Description** from the list and click **Create**.
Copy file name to clipboardExpand all lines: articles/getting_started/content_pipeline/custom_effects.md
-3Lines changed: 0 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,6 @@ title: Custom Effects
3
3
description: Learn how to create and use custom effects for rendering in MonoGame.
4
4
---
5
5
6
-
# Custom Effects
7
-
8
6
A core element of Microsoft XNA is the effect system which is used for all rendering.
9
7
10
8
For MonoGame we have the burden of supporting stock and custom effects for desktop GLSL, mobile GLSL, DirectX HLSL, and custom formats like that of the PlayStation Mobile. There currently is no effect system or shader language that supports all the platforms we require, forcing us to build a new custom effect system.
@@ -64,7 +62,6 @@ These are some tips for writing or converting effects for use with MonoGame.
64
62
|`HLSL` and `SM4` for DirectX |
65
63
|`OpenGL` and `GLSL` for OpenGL |
66
64
67
-
68
65
As an example, you can conditionally set shader models depending on the platform with the following code:
Copy file name to clipboardExpand all lines: articles/getting_started/content_pipeline/index.md
-2Lines changed: 0 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,6 @@ title: Adding Content
3
3
description: Learn how to add content to your game using the Content Pipeline.
4
4
---
5
5
6
-
# Adding Content
7
-
8
6
A big part of your game is your content. This includes standard files like textures, sound effects, music, videos, and custom effects as well as custom content like level and enemy files.
9
7
10
8
MonoGame implements its own content pipeline for transforming your unoptimized assets into platform optimized content. This is critical in building a game which runs as fast as possible under tight resource constraints.
Copy file name to clipboardExpand all lines: articles/getting_started/content_pipeline/localization.md
+1-3Lines changed: 1 addition & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -3,8 +3,6 @@ title: Localization
3
3
description: Learn how to add localization to your game to support multiple regions.
4
4
---
5
5
6
-
# Localization
7
-
8
6
Localization is an important part of any game. While it can be possible to design a game that is region independent, it is quite hard. At some point you will need to produce localized text and graphics.
9
7
10
8
MonoGame has a simple localization system built in. If you want to develop your own system you are still able to do so. But the default system should be good enough for
which are part of the **System.Globalization namespace**.
136
+
which are part of the **System.Globalization namespace**.
139
137
140
138
> On a side note you can also use the `LoadLocalized` to load language specific SpriteFonts. They just need to be named in the same way as we have described above.
0 commit comments