Announcement

Collapse
No announcement yet.

C++ Documentation Improvement Push

Collapse
X
 
  • Filter
  • Time
  • Show
Clear All
new posts

    C++ Documentation Improvement Push

    I understand that you have a limited support team and that you guys are working hard to improve and push forward the documentation for the engine, however, there is a large difference in the amount of official support directed at C++ and blueprints.
    For instance, in the following link is the official Gameplay Guide, at the bottom you can jump down and see the Gameplay How To's:
    https://docs.unrealengine.com/latest...lay/index.html

    The documentation there clearly states the intent for C++ to be a part of that documentation, and previous staff comments have suggested that those bits of documentation would be coming "soon", however, those pages and those comments are a few months old now. Why does the C++ documentation consistently play second fiddle?

    I understand that you guys have a lot to do, but even basic C++ examples have not been addressed within the documentation, yes there are templates and example projects but those are big "chunk" examples, the problem with those examples is that for a beginner who has little understanding of the engine breaking those chunks into manageable pieces involves either jumping through a multitude of links in the documentation or meandering through the entirety of the code base, often which requires jumping from class to class to class to find the comment section that actually expands on what the functions purpose is or what parameters are looking for/mean (and usually fail to explain where to use the function or how to use it properly). This would be perfectly acceptable for more obscure functions and advanced use-cases, but this is for the most basic of functions. So after reading through the sticky, "UE4 Editor Terminology: We need your feedback!", I wanted to offer a suggestion for your documentation efforts to help improve the engine's usability for beginners looking to work on the C++ aspect of the engine.

    I would like to put forward the idea of micro-tutorials (text based) for C++ (similar to the multitude of video series done for blueprint) that cover the most important classes and architectural aspects of the engine as well as their key functions. For instance lets take gamemode, right now we have the following page:
    https://docs.unrealengine.com/latest...ode/index.html

    However, in that page there is nothing that examines concretely how to actually work with GameMode, for instance the page starts with:
    Even the most open-ended game has an underpinning of rules, and these rules make up a gametype.
    Great! Nice start, stating the most basic premise of what a GameMode is, then we continue with...
    On the most basic level, these rules include:
    • The number of players and spectators present, as well as the maximum number of players and spectators allowed.
    • How players enter the game, which can include spawn locations and spawn/respawn behavior.
    • Whether or not the game can be paused, and how pausing the game is handled.
    • Transitions between levels, including whether or not the game should start in cinematic mode.
    Oh okay, gotcha, so that all makes sense, but how do we actually do any of that? Maybe if we continue on...?
    ...
    Hmm... Nope. Nothing else that gives a beginner an inkling of how to actually have a GameMode interact with their game.
    Maybe we try google? -"Unreal Engine GameMode"-

    Well we get a link to the page we just passed over, then a promising one "Unreal Engine | How to Set Up a Game Mode in Blueprints", ah, that must be useful to use right!?
    https://docs.unrealengine.com/latest...nts/index.html

    ...
    Hmm, well I can make a blueprint GameMode and set a Default Pawn Class and even assign a Default Game Mode, but there is no further progress on what a GameMode is actually suppose to do or how it should be used to communicate with the rest of our game. (Note that the above is actually from the gameplay guide which currently excludes C++ content)

    Alright so we struck out, lets try again, lets venture to one of the templates, maybe one of those will have a good explanation of what we're suppose to do with our GameMode...
    I freshly opened up a Top Down template, so lets take a look at what's in the GameMode header...
    Code:
    UCLASS(minimalapi)
    class ATopDownGameMode : public AGameMode
    {
    	GENERATED_BODY()
    
    public:
    	ATopDownGameMode(const FObjectInitializer& ObjectInitializer);
    };
    Hmm... Not much of use for figuring out how to make a limit to the number of players, nor does it help us understand how to determine how players will enter the game, nothing to suggest how to pause the game either, and nothing in there telling us how to transition between levels...

    Alright... Well what about the .cpp file?
    Code:
    ATopDownGameMode::ATopDownGameMode(const FObjectInitializer& ObjectInitializer) : Super(ObjectInitializer)
    {
    	// use our custom PlayerController class
    	PlayerControllerClass = ATopDownPlayerController::StaticClass();
    
    	// set default pawn class to our Blueprinted character
    	static ConstructorHelpers::FClassFinder<APawn> PlayerPawnBPClass(TEXT("/Game/Blueprints/MyCharacter"));
    	if (PlayerPawnBPClass.Class != NULL)
    	{
    		DefaultPawnClass = PlayerPawnBPClass.Class;
    	}
    }
    Yeah... Not much information in there about anything the entire GameMode information page was going on about...
    Well its just a template right? Lets try the bulkier "Sample Game". Who doesn't love strategy games?

    So we open up the Strategy Game solution and find the GameMode:
    Code:
    UCLASS(config=Game)
    class AStrategyGameMode : public AGameMode
    {
    	GENERATED_UCLASS_BODY()
    
    	/** Class for empty wall slot. */
    	UPROPERTY()
    	TSubclassOf<AStrategyBuilding> EmptyWallSlotClass;
    
    	/** Time before game returns to menu after finish. */
    	UPROPERTY(config)
    	int32 TimeBeforeReturnToMenu;
    
    	/** Name of the difficulty param on the URL options string. */
    	static const FString DifficultyOptionName;
    	
    	// Begin GameMode interface
    
    	/** Initialize the GameState actor. */
    	virtual void InitGameState() override;
    
    	/** 
    	 * Handle new player, skips pawn spawning. 
    	 * @param NewPlayer	
    	 */
    	virtual void RestartPlayer(class AController* NewPlayer) override;
    	
    	/** 
    	 * Modify the damage we want to apply to an actor.
    	 * 
    	  * @param Damage			The damage
    	  * @param DamagedActor		The actor we wish to damage
    	  * @param DamageEvent		The event that caused the damage
    	  * @param EventInstigator	
    	  * @param DamageCauser
    	  *
    	  * @returns The adjusted damage amount
    	  */
    	virtual float ModifyDamage(float Damage, AActor* DamagedActor, struct FDamageEvent const& DamageEvent, AController* EventInstigator, AActor* DamageCauser) const;
    
    	// End GameMode interface
    
    	/** 
    	 * Finish the game with selected team as winner.
    	 *
    	 * @param	InWinningTeam		The team that has won.
    	 */
    	UFUNCTION(BlueprintCallable, Category=Game)
    	void FinishGame(EStrategyTeam::Type InWinningTeam);
    
    	void ReturnToMenu();
    
    	/** 
    	 * Helper function to test teams (null = not in friendly team). 
    	 *
    	 * @param ActorA		First actor to test against
    	 * @param ActorB		Second actor to test against
    	 *
    	 * @return true if the two actors are on the same team.
    	 */
    	static bool OnFriendlyTeam(const AActor* ActorA, const AActor* ActorB);
    
    	/** 
    	 * Helper function to test teams (null = not in friendly team). 
    	 *
    	 * @param ActorA		First actor to test against
    	 * @param ActorB		Second actor to test against
    	 *
    	 * @return true if the two actors are on opposing teams.
    	 */	
    	static bool OnEnemyTeam(const AActor* ActorA, const AActor* ActorB);
    
    	/** Helper method for UI, to exit game. */
    	void ExitGame();
    
    	/** Pointer to title text widget. */
    	TSharedPtr<class SStrategyTitle> StrategyTitle;
    
    protected:
    	/* Helper to return the current gameplay state. */
    	EGameplayState::Type GetGameplayState() const;
    
    };
    Alright cool, finally we get to see what a gamemode might look like, awesome, but... as a beginner this isn't particularly useful as most of the comments are simply explanations of the function's effect or parameters, not a discussion on the composition of the function nor what the parts of the functions are doing, heck, StrategyGameMode.cpp has hardly any comments or explanations, not exactly a gold star in teaching materials. This means we're going to have to first decipher the structure of the game to figure out how the GameMode is supposed to work... Hmm... Wait, I remember seeing something that covered the important bits of the Strategy Game!
    https://docs.unrealengine.com/latest...ame/index.html

    Wait... looking through this there is nothing that actually helps to answer our question, "How do I properly work with/use a GameMode?" In fact that entire page doesn't cover nor dissect a single line of code, a bunch of functions are brought up, but for some reason no one actually mentions where these functions are located in our source files. Darn, I thought this would be the one to really help me figure out how I'm supposed to work in the Unreal Engine.

    Oh well, I guess I'd better start guessing and misinterpreting the engine!

    I hope the above playful attitude didn't insult anyone.

    The point I'm trying to make is that while many people say to "just look through the source files and examples", the problem with that is that the engine is so enormous that a trip through the all the functions located in simply the GameMode file of the strategy game would have beginners jumping through half the engine files trying to figure out what's going on, right now there is no guided approach to actually learning the engine, it's similar to giving a person a pencil and a book of Michelangelo's sketches and telling them to just figure it out. Yes, that is how many people learn to draw (copying relentlessly) but the problem with that is that the approach is highly ineffective as it relies on bulk repetition and happenstance, there are reasons why people study anatomy, lighting, composition, because mindless copying isn't understanding, nor is the approach new developers are forced through when facing UE4, so while you can learn UE4 through doing this, it isn't a good way by any means, anyone who says otherwise is exhibiting a case of survivorship bias.

    So, returning to the point of this post, can we please get targeted C++ training that not only gives an overview of the class but also how to use it, the important functions within the class, and then examples of proper use of the classes, for example maybe we have a basic example of a pong game that connects how to use game mode and a player controller and a game state together. Then another that explains how we would use a GameMode in an rpg, WITH accompanying code, that actually shows a concrete example of the way to communicate between the GameMode and other pieces of the game.

    For starters the classes on the following page that get bold headers would be a good start for providing concrete code examples and explanations:
    https://docs.unrealengine.com/latest...nce/index.html

    In case you don't want to follow the link the classes in there are:
    • Pawn
    • Character
    • Controller
    • PlayerController
    • AIController
    • HUD
    • Camera
    • GameMode
    • GameState
    • PlayerState


    That's 10 items that help to form the core of the engine and yet, there is (from what I've seen) no official documentation that covers and explains both the theoretical and concrete use of these classes.

    To explain what I'm looking for in the documentation lets ask some sample questions that they should be able to answer:
    Pawn/Character:
    How do I spawn a new pawn or character? How do I connect these new pawns/characters to the PlayerController or an AIController? Where should I place the code that would instantiate these new pawns/characters? What are the most important/useful functions and variables?

    PlayerController/AiController:
    What is the proper way to work with these controllers? What are some usage examples? How should I spawn multiple controllers to control multiple different AI? What if I spawn a character in the middle of gameplay (like a rts unit)? How does someone handle a manager class in UE4 (one responsible for making AI work together/cooperate)? What are the most important/useful functions and variables?

    HUD:
    Explain canvas versus slate versus UMG. Which should be used when? What is the workflow for working with each when using C++? What are the most important/useful functions and variables?

    Camera:
    How to deal with more complex camera behavior than "sit and stay behind this character and do nothing else"? How to make a zooming third person camera, how to make it transition to first person? How to make an rts camera, how to link that to an rts map? How should we handle jumping between different characters, do we use multiple cameras or detach the camera and connect it to the other character? What are the most important/useful functions and variables?

    GameMode:
    Explain the connection between GameMode and UGameEngine, as well as the connection with PlayerStarts? How might we change how PlayerStarts work, where would we do that in the code? How would we implement any of the examples you guys put forward in your GameMode "explanation" page? What's the connection between GameState and PlayerState? Does GameMode act as a manager class? What are the most important/useful functions and variables?

    GameState:
    When do we use the GameState class? What should we use it for? What are some examples? How should we access our GameState? What are the most important/useful functions and variables?

    PlayerState:
    When do we use the PlayerState? What do we put in the PlayerState that we don't put in our GameState and vice versa? Show us some examples and implementations. How should we access and work with this class? What are the most important/useful functions and variables?

    #2
    Hey Cidubic, thank you for taking the time to post!

    I assure you this is high priority and it is personally my sole focus for the foreseeable future. We are acutely aware that the C++ side of things in the documentation is lacking, especially when compared to something like Blueprints.

    We just had a meeting today to discuss items to tackle and more are planned for tomorrow and Friday. I think pretty much everything you are asking for is on the list of tasks to tackle.

    These things do take time and there is often a lot going on that you guys don't see, but I hope you will start to see tangible progress very soon.
    Unreal Engine Documentation
    Bored? Follow me! @ffejnosliw

    Comment


      #3
      Glad to hear that Jeff Wilson! Thank you for taking the time to respond and I'm now looking forward to the coming weeks.

      Comment


        #4
        That makes me excited as well. That has been my major roadblock when trying to make my first game in UE4. William Sherif released a book on PacktPub 2 days ago about C++ and UE4 but I have no idea how good it is and have heard no feedback. Hope Epic will make a thorough guide.

        Comment


          #5
          Jeff,

          It’s great to see the additional emphasis on UE4, C++ instruction.

          I’d like to highlight Cidubic's mention of text-based (written) C++ tutorials. For C++, written tutorials may be more effective than video tutorials over time. Written tutorials are easier to reference (nonlinear, searchable, etc.) than video, and the C++ in written tutorials can be easily updated to reflect changes in engine/game versions. Sample games, accompanying the tutorials, could provide the “live" visual. Many of the C++ videos cause frustration when they simply do not work with updated versions of the engine.

          "Instructional Design is the practice of creating instructional experiences which make the acquisition of knowledge and skill more efficient, effective, and appealing."

          Comment


            #6
            In case you haven't seen the new C++ documentation tutorials that were released with 4.7, Epic released a few nice text tutorials that give a glimpse of what is in store for us:
            https://docs.unrealengine.com/latest...als/index.html

            Comment


              #7
              Our focus during these improvements so far has been completely on written tutorials. There are several that are already available in the documentation and I would expect more to be available in the coming months.

              We may still do additional video series for those that do prefer that medium, though. The fact is that everyone learns differently and we want to make sure we accommodate as many people as possible.
              Unreal Engine Documentation
              Bored? Follow me! @ffejnosliw

              Comment


                #8
                Originally posted by Jeff Wilson View Post
                Hey Cidubic, thank you for taking the time to post!

                I assure you this is high priority and it is personally my sole focus for the foreseeable future. We are acutely aware that the C++ side of things in the documentation is lacking, especially when compared to something like Blueprints.

                We just had a meeting today to discuss items to tackle and more are planned for tomorrow and Friday. I think pretty much everything you are asking for is on the list of tasks to tackle.

                These things do take time and there is often a lot going on that you guys don't see, but I hope you will start to see tangible progress very soon.
                Hi Jeff... Anything on the way? I just went to the page almost 10 months later and I do not see anything new... Am I missing something?

                teak
                "A little bit of nonsense now and then is cherished by the wisest men..."
                -- Willy Wonka

                Smooth Zoom Camera Plugin for 4.24 here.

                Comment


                  #9
                  Bump... awaiting response from Epic for such an old request...and... a because there was such a forceful response from Epic about the topic. Thanks!
                  "A little bit of nonsense now and then is cherished by the wisest men..."
                  -- Willy Wonka

                  Smooth Zoom Camera Plugin for 4.24 here.

                  Comment


                    #10
                    I also agree. I am frustrated by the lack of c++ learning resources compared to blue prints. I have to rely on outdated information or information from users.

                    Comment


                      #11
                      Originally posted by NovanMK2 View Post
                      I also agree. I am frustrated by the lack of c++ learning resources compared to blue prints. I have to rely on outdated information or information from users.
                      Hopefully, we will get something "official" from Epic... I am really enjoying using the engine, but wish the level of documentation for C++ was close to Blueprints....
                      "A little bit of nonsense now and then is cherished by the wisest men..."
                      -- Willy Wonka

                      Smooth Zoom Camera Plugin for 4.24 here.

                      Comment


                        #12
                        there is a lot of video tutorial for blueprint in unreal youtube channel and ... , but im really hope epic make more tutorials (specially video tutorial) for C++ too

                        Comment


                          #13
                          Found a tutorial on the youtube channel that's good... Just need more! And, updated documentation of course......

                          https://goo.gl/wnxIb4

                          teak
                          "A little bit of nonsense now and then is cherished by the wisest men..."
                          -- Willy Wonka

                          Smooth Zoom Camera Plugin for 4.24 here.

                          Comment


                            #14
                            Another Youtube playlist listed here! ....

                            https://goo.gl/xkaCya

                            Has anyone tried merging their already-made Blueprint code into C++?
                            I'd like to get feedback as to how many days it may take and how smooth and fast it will be when I'm done, compared to programming with Blueprint. Will the quality of the textures & images improve as well as speed and functionality? I'm a newbie just two weeks along but nearly finished my first project. I started looking into C++ because performance is important to me. Look forward to hearing feedback!

                            Comment

                            Working...
                            X